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e Serasa Experian. Como consultor, prestei serviços para empresas 
dos mais diversos segmentos de atuação, como Netshoes, CVC, 
Magazine Luiza, iG, Oi internet, e muitas outras. 


Por muitos anos, trabalhei como especialista em SOA. Desde o 
início procurei sempre ter em mente a concepção original desta 
arquitetura - algo muito próximo ao que hoje reconhecemos como 
microsserviços. Esta experiência me levou a adotar REST ainda em 
seus primórdios no país. Utilizei REST pela primeira vez em um 
projeto em 2011, em projeto para o iG. Desde então, venho 
estudando cada vez mais sobre o assunto e procurando entender a 
forma como esta técnica ajuda desenvolvedores em todo o mundo 
a oferecer aplicações cada vez mais interconectadas. 


INTRODUÇÃO 


Este livro nasceu com uma proposta de ser uma segunda 
versão do meu livro REST: Construa APT's inteligentes de maneira 
simples. Ele tinha sido publicado originalmente em 2013, então eu 
achava que ele merecia uma revisão dos tópicos, sete anos depois. 


No processo de reescrita algo aconteceu. Percebi que queria 
um livro mais pragmático, mais conectado à realidade brasileira - a 
necessidade de um livro com resultados mais práticos, mais ligados 
ao dia a dia dos desenvolvedores brasileiros. Quando fiz isso, 
comecei a ignorar o livro anterior e escrever este livro do zero. 


O resultado foi um livro que apresenta a parte teórica apenas 
quando requisitada pela parte prática. Em outras palavras, a teoria 
se faz presente apenas quando ela é requisitada para que se cumpra 
o objetivo da prática. 


A partir dessa concepção, segui com a escrita. Passei a abordar 
muito mais coisas sobre APIs e não apenas sobre REST. E daí notei 
que seria mais interessante dividir o livro em duas partes: a 
primeira, mais voltada à parte mais básica sobre serviços REST e 
por onde iniciar esse desenvolvimento. A segunda parte, sobre 
APIs, procura abordar mais as questões necessárias para que os 
serviços REST sejam realmente aproveitados por outros 
desenvolvedores. Em outras palavras, como podemos criar APIs 
expostas para o público. 


Assim sendo, este livro foi dividido nos seguintes capítulos: 


O capítulo 1 apresenta o aplicativo C.A.R. , que faz 


intermediação entre pessoas que precisam de um transporte rapido 
e motoristas que possuem um carro e podem fazer esse transporte. 
Neste capitulo, vamos criar a primeira API do aplicativo, que 
recupera dados de passageiros. Apresento alguns conceitos basicos, 
como quais são os principais métodos HTTP necessários para 
desenvolver uma API REST. 


No capítulo 2 esta API é expandida, e daí vemos como 
recuperar dados de passageiros específicos, além de como criar 
estes dados, atualizar (total ou parcial) e apagar - tudo isso com um 
cliente especializado, o Postman . Também veremos como 
funciona um dos pilares fundamentais de REST, o da negociação 
de conteúdo, e conheceremos o que é idempotência e seus efeitos 
práticos sobre as APIs. 


No capítulo 3 nós vamos criar a API de solicitação de viagens, e 
vamos relacionar esta API com a de gerenciamento de passageiros 
através do uso de HATEOAS (uma das técnicas mais importantes 
de REST). 


No capítulo 4 nós vamos utilizar o serviço do Google Maps 
para incrementar a API criada no capítulo anterior. Desta forma, 
veremos como criar um cliente de uma API REST e também 
vamos conhecer o JSONPath, uma poderosa técnica de busca de 
dados dentro de um documento JSON. 


No capítulo 5 nós vamos realizar os testes de ponta a ponta. 
Vamos aprender como criar um dublê do serviço do Google Maps 
com o Wiremock (desta forma, dispensando o consumo da API 
quando estivermos executando os testes) e também vamos 
aprender a usar uma ferramenta especializada em testes de serviços 
REST, o REST Assured. 


No capítulo 6 vamos acrescentar uma camada de segurança 
nos nossos serviços. Vamos ver como funciona o HTTPS, e 
também vamos gerar um certificado e implantá-lo na nossa API. 
Também vamos implantar autenticação BASIC nas nossas APIs. 


A partir do capítulo 7, inicia-se a segunda parte do livro, sobre 
APIs. Esse capítulo vai utilizar os conhecimentos já adquiridos ao 
longo do livro e os sedimenta. Então, veremos como criar URLs 
mais significativas para nossos clientes, quais os códigos HTTP 
mais importantes, como fornecer mensagens de erro significativas, 
como internacionalizar as mensagens de erro e, finalmente, como 
criar APIs retrocompatíveis (técnica muito importante em casos de 
APIs públicas ou aplicativos mobile). 


No capítulo 8 nós vamos aprender a documentar nossas APIs. 
Vamos criar uma API viva com Swagger e também veremos 
como usar o Documenter do Postman . 


No capitulo 9, veremos algumas técnicas que nao puderam ser 
abordadas ao longo do livro. Veremos como paginar serviços, 
implementar a técnica CORS (importante para consumir os 
serviços REST a partir de páginas web), autenticação com OAuth 
e, finalmente, como utilizar o AWS API Gateway para que 
possamos ter mais segurança ao expor APIs públicas. Apresentarei 
como criar e utilizar sua conta na AWS de forma controlada, para 
que não haja problemas em relação aos custos. 


No capítulo 10, apresento algumas tecnologias que não estão 
necessariamente relacionadas às APIs em REST, mas fazem parte 
de um ecossistema mais amplo de APIs. 


Este livro foi escrito com muito carinho, levando em 


consideração a bagagem que acumulei ao longo dos anos e 
também como resultado de muitas conversas com desenvolvedores 
como vocé. Desta forma, procurei abordar os conceitos que tive 
como mais importantes. Caso vocé, leitor ou leitora, sinta que 
algum conceito nao esta suficientemente claro, ou tenha sentido 
falta de alguma técnica, sinta-se 4 vontade para entrar em contato 
comigo diretamente, através do e-mail alesaudate@gmail.com. Este 
é meu compromisso com você. 


PRÉ-REQUISITOS 


Este livro é uma história contada sobre uma aplicação fictícia 
chamada C.A.R. , um aplicativo para solicitação de carros para 
viagens curtas. Esta aplicação é desenvolvida em Java 8, utilizando 
o Spring Boot como framework para basear tudo e Maven como 
controlador de build. 


Estas ferramentas foram escolhidas como aquelas que podem 
alcançar o maior número de leitores, não por serem as mais 
recentes ou por serem as “melhores”. Ainda assim, a simplicidade 
é o principal conceito utilizado aqui - procurei escrever todos os 
exemplos de forma que, mesmo que você não tenha conhecimento 
sobre Spring Boot ou nem mesmo seja desenvolvedor(a) Java, 
consiga acompanhar os conceitos. Mas o ideal, mesmo, é que você 
acompanhe os exemplos reescrevendo os exemplos em sua própria 
máquina e “brincando” com os conceitos apresentados. Tenho 
certeza que, desta forma, você conseguirá tirar o máximo proveito 
do que apresento aqui. 
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Servicos em REST 


CAPITULO 1 


O QUE É REST, AFINAL? 


"Quem conduz e arrasta o mundo não são as máquinas, são as 
ideias.” - Victor Hugo 


Hoje em dia, muito se ouve falar de REST e você, como um 
desenvolvedor ou desenvolvedora de software, já deve ter ouvido 
falar desse termo. Trata-se de um meio de realizar a comunicação 
entre dois sistemas diferentes (independente da linguagem em que 
tenham sido escritos). 


Obviamente, existem muitas formas de se fazer isso. Mas o fato 
é que REST estabelece um conjunto de padrões que permite fazer 
isso de forma eficiente e interoperável (coisas que, considerando 
cenários de microsserviços, por exemplo, se tornam especialmente 
interessantes de se possuir). 
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O QUE SAO MICROSSERVIÇOS? 


Segundo Martin Fowler, "...0 estilo de arquitetura de 
microsserviços é uma abordagem que desenvolve um 
aplicativo único como uma suíte de pequenos serviços, cada 
um executando seu próprio processo e se comunicando 
através de mecanismos leves, muitas vezes em uma API com 
recursos HTTP. Esses serviços são construídos em torno de 
capacidades de negócios e funcionam através de mecanismos 
de deploy independentes totalmente automatizados. Há o 
mínimo possível de gerenciamento centralizado desses 
serviços, que podem ser escritos em diferentes linguagens de 


programação e utilizam diferentes tecnologias de 
armazenamento de dados." (LEWIS; FOWLER, 2015) 





Analisemos um case: considere que você é o principal 
desenvolvedor do back-end de um aplicativo para solicitar 
transporte de carros (em modelo semelhante ao de táxis, como o 
daquela empresa que começa com U, sabe?). Esse aplicativo se 
chama C.A.R. e sua missão é promover o melhor meio de 
transporte possível pelo menor preço possível, conectando pessoas 
que possuem carros e gostariam de usá-lo para ter uma renda extra 
com pessoas que precisam de um meio de transporte. 


Você está encarregado de criar o back-end, enquanto outros 
desenvolvedores vão construir o front-end (tanto em versão web 
quanto mobile). 


10 QUE É REST, AFINAL? 3 


1.1 UTILIZANDO O SPRING BOOT PARA 
CRIAR UMA PRIMEIRA API 


Uma das maneiras mais rápidas de se iniciar um projeto de 
uma API REST em Java hoje em dia é através do uso de algum 
framework. O framework Java mais popular é o Spring, que na 
verdade provê diversas capacidades para o projeto, sendo que a 
disponibilização e gerenciamento de ferramentas para construção 
de APIs é apenas um de seus aspectos. O Spring, no entanto, é 
também um dos frameworks Java mais antigos, sendo que ele tem 
um subprojeto chamado Spring Boot, cujo objetivo é tornar a 
utilização do Spring tão rápida e prática quanto possível. 


O Spring também conta com um site chamado Spring Initializr 
(https://start.spring.io/). Nele, é possível selecionar quais 
capacidades vamos querer no projeto, quais outros possíveis 
frameworks Java vamos querer utilizar etc. 


OBSERVAÇÃO SOBRE O SPRING INITIALIZR 


Como sabemos, o mercado de desenvolvimento de software é 
muito dinâmico, e pode ser que o Spring Initializr tenha uma 
interface diferente ou mesmo não exista mais na época em 
que você ler este livro. No entanto, como mencionado, o 
Spring é um dos frameworks mais antigos e mais bem 
estabelecidos do Java, e tudo indica que sua existência vai 
permanecer enquanto houver Java - logo, provavelmente o 
Spring Initializr vai continuar existindo ou vai existir algo 


melhor na época que você estiver lendo. 
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Ao acessar o site, você deve se deparar com uma tela 
semelhante a seguinte: 


initializr 


ADO DEPENDENCIES... C 





GENERATE CTRL + EXPLORE CTRL + SPACE 


Figura 1.1: Tela do Spring Initializr 


Aqui, você tem a opção de selecionar o sistema de build para 
seu projeto (Maven ou Gradle), a linguagem (Java, Kotlin ou 
Groovy), a versão do Spring Boot, alguns metadados sobre o 
projeto e as dependências. Para manter a consistência, vou utilizar 
ao longo deste livro, em todos os projetos, o Maven com 
linguagem Java 8 e Spring Boot versão 2.2.0. Os metadados devem 
variar de capítulo para capítulo - caso queira conferir exatamente 
quais serão, basta verificar o código-fonte do projeto no GitHub 
(disponível em https://github.com/alesaudate/rest-v2). Finalmente, 
as india derem variar de capítulo para a por conta 
das necessidades, mas vou avisá-lo de acordo com as mudanças 
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destas. 


Para este capítulo, precisamos utilizar o Spring Web e o Spring 
Data JPA como dependências. Para que a listagem apareça, digite 
as primeiras letras de web e data e a listagem de dependências deve 
ficar semelhante à seguinte: 


we 


Spring Web | wee | 
B eb, including RESTiul, apr 


Tiymeleat 


Spring Web Services [TH 


Repositories | wes | 


Spring Session | wes | 





Figura 1.2: Tela das dependências do Spring 


Por fim, aperte o botão Generate e o download de um 
arquivo zip deve ser iniciado, contendo o seguinte conteúdo: 
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mv 53,1kB 


src 509 bytes 
=| .gitignore 333 bytes 
-| HELP.md 780 bytes 
i | mvnw 9,1 kB 
i | mvnw.cmd 5,8kB 
n| pom.xml 1,4kB 


Figura 1.3: ZIP do projeto 


Observe que o arquivo HELP.md já vem com alguns links úteis 
para uso das ferramentas escolhidas (no caso, Maven, Spring Boot 
e Spring Web) e também alguns guias a respeito de como construir 
serviços REST com as ferramentas escolhidas. Copio a seguir os 
links para ajuda-lo em seus estudos: 


e Building a RESTful Web Service - 
https://spring.io/guides/gs/rest-service 

e Serving Web Content with Spring MVC - 
https://spring.io/guides/gs/serving-web-content 

e Building REST services with Spring - 
https://spring.io/guides/tutorials/bookmarks 


Já o projeto em si pode ser importado da forma como está em 
sua IDE. Ao longo deste livro, vou utilizar o Intellij - você pode 
usar a IDE de sua conveniência. A estrutura do projeto é a 
seguinte: 
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cap01 ~/workspace/rest/cap01 


» B mvn 
v Misrc 
y B main 
v M java 
* B app 
v acar 
y D cap01 
‘© Capo1Application 
y B resources 
Bm static 
M templates 
di application.properties 
vy Ba test 
+ M java 
7 D app 
v car 
+ Es cap01 
‘© Cap01ApplicationTests 
» M target 
& HELP.md 
= mvnw 
2 mvnw.cmd 
M pom.xml 


Figura 1.4: Estrutura do projeto 


O Spring Boot faz o download de um web server para nós (o 
padrão no momento é o Tomcat, mas existem outros disponíveis, 
como Jetty e Undertow). Para inicializar o sistema, basta executar 
o método main da classe Cap01Application . O log deve ficar 
semelhante ao seguinte: 


i main] app .car capo! CapOiapplication + Starting Copolasplicatica on ná-17035-0 with PIO 72690 (/home/asauc 
í maia] app. car cap0l.Capoappl ication $ No active profile set, falling back to default profiles: default 

1 main] 0.5,d.v.entedded. tomcat. TomcatimbServer ; Tomcat initialized with portis): 968 (bttp) 

{ main) o.apache.catalina. Fina StandardService : Starting service [Toscat] 

! main] org.apache.estalina.core StandardEngina : Starting Servlet engine: [Apache Toscat/9.0.27] 

I 

if 

1 





rdEng: 
tain] o re e e [Tomcat]. localhost (7) = ioltiatérioo spring enbedeed sutapolcsricacantant 
main] 0.%.web.costent Costenticadar + Root webapplicationCenteat: initialization completed in 3533 4 
aul 0.5. £.concerrent .TareadPoolTaskexecutor : Initializing Executorservice application raskexecut 
o. meses + pi ie ud É Tomcat started en portis): Biao http) with context path * 
fi Er app car .cag@) 1 Started CapOlApplication in 2.758 seconds (JVM running for 3.239) 
vrs [nto-O080-enec-3] 0.8.€.€.C. Frost Nealon), ul : Initializing Spring Oispatcherserviet ‘dispatcherservlet 
-— [eko-0080-exec-3] 0.¥.web. servlet Otspatcherserviet i Initializing Servier "dispute beriorviaa 
-— Into-BBBO-exec-3] 0.9, web. serviet .Dispatchertervlot : — initialization ie 7 
lextShutdowriook! 0.5.5. concurrent. ThreadPootTaskExecutor : Shvtting dan Executerservice “Soplicatsonraskexecvter 


Figura 1.5: Log do projeto 
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1.2 O PRIMEIRO CASO DE USO: A LISTAGEM 
DE NOVOS MOTORISTAS 


Vamos agora criar um primeiro serviço em REST para atender 
a um caso de uso. O aplicativo C.A.R. precisa de um back-end de 
administração, ou seja, um programa através do qual seja possível 
controlar quem são os motoristas, os passageiros, as corridas 
realizadas etc. Esse primeiro caso de uso vai precisar de um serviço 
para listar os motoristas cadastrados, algo que faça o acesso ao 
banco de dados do sistema e retorne os dados dos motoristas. 
Como fazer isso? 


Em primeiro lugar, precisamos criar uma camada de acesso a 
um banco de dados e uma classe que representará os motoristas. 
Como prática pessoal, eu prefiro escrever código em inglês (para 
manter a harmonia entre as palavras reservadas da linguagem e o 
código que estou escrevendo). Assim sendo, vou criar um pacote 

domain e, dentro dele, uma classe chamada Driver : 


“> cap01 
- .mvn 
src 
main 
7 java 
7 app 
car 
y cap01 
‘© Driver 
infrastructure 
© Cap01Application 
= resources 
static 
templates 


i application.properties 


Figura 1.6: Classe que representa o motorista criada 
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Agora, vamos incluir alguns dados para esse motorista, 
digamos, um campo id, name e birthDate : 


package app.car.cap01.domain; 
import java.util.Date; 
public class Driver { 


Long id; 
String name; 
Date birthDate; 


Precisamos agora gerar getters e setters para os campos gerados. 
Eu costumo utilizar um framework para lidar com essas questões 
chamado lombok. Ele trabalha com uma abordagem em que você 
anota suas classes e ele gera o código correspondente para você. 
Para isso, no entanto, é necessário instalar o próprio lombok sobre 
a IDE para que ela reconheça que o código será gerado e não 
produza eventuais erros de compilação. Como nem todos se 
sentem confortáveis com este processo, saiba que é totalmente 
opcional (o lombok gera o código, mas na própria pagina do 
framework são mostrados os códigos equivalentes sem o uso dele). 


Caso você, assim como eu, queira usar o lombok, precisamos 
apenas adicionar uma dependência no projeto (ou voltar ao passo 
de criação do projeto no Spring Initializr e marcá-lo como uma 
dependência). Para isso, basta incluir na seção de dependências no 

pom.xml a declaração de dependência do lombok: 
<dependency> 
<groupId>org.projectlombok</groupId> 
<artifactId>lombok</artifactId> 


<optional>true</optional> 
</dependency> 
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Feito isso, anotamos a classe Driver com a anotação @Data 
do lombok ou criamos os getters, setters, métodos equals e 
hashcode manualmente. O código fica assim: 


package app.car.cap01.domain; 


import java.util.Date; 
import lombok.Data; 


@Data 
public class Driver { 


Long id; 
String name; 
Date birthDate; 


Agora precisamos modificar essa classe para refletir o estado de 
nosso banco de dados. Fazer isso em Java também é fácil, basta 
anotar a classe com javax.persistence.Entity . Além disso, 
também vamos fazer com que o sistema reconheça o campo id 
como representante da chave primária da tabela correspondente. 
Fazemos isto com a anotação javax.persistence.Id : 


package app.car.cap01.domain; 


import java.util.Date; 

import javax.persistence.Entity; 
import javax.persistence.Id; 
import lombok.Data; 


@Data 
@Entity 
public class Driver { 


@Id 

Long id; 

String name; 
Date birthDate; 
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Agora, precisamos de um meio de acesso ao banco de dados 
(algo semelhante aos design patterns DAO ou Repository , 
conforme orientado pelo Domain-Driven Design). Quando 
utilizamos o Spring Data JPA, isso se resume a criar uma interface 
e fazer com que ela estenda outra, a JpaRepository . Esta outra 
interface utiliza o mecanismo de generics do Java. Na declaração 
dela, ela utiliza a classe que é gerenciada por este repositório e a 
classe da chave primária (no nosso caso, java. lang.Long - 
observe o L maiúsculo). 


Vamos chamar nosso repositório de DriverRepository 
Realizando a extensão da interface mencionada, temos o seguinte: 


package app.car.cap01.domain; 
import org.springframework. data. jpa.repository. JpaRepository; 


public interface DriverRepository 
extends JpaRepository<Driver, Long> { 


} 


O próximo passo é escolher e configurar o banco de dados 
escolhido. Algumas vezes, em desenvolvimento, utilizamos um 
banco de dados em memória apenas para podermos validar algum 
código que desenvolvemos. Uma boa pedida para o nosso contexto 
é o H2, que é um banco de dados que inicializa junto com o nosso 
projeto e também tem uma interface de administração fornecida 
através de uma extensão do Spring Boot, o Spring Boot DevTools. 


Para incluirmos as duas dependências no nosso projeto, 
colocamos a seguinte declaração de dependências no pom.xml : 


<dependency> 
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<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot -devtools</artifactId> 
<optional>true</optional> 

</dependency> 


<dependency> 
<groupId>com.h2database</groupId> 
<artifactId>h2</artifactId> 
</dependency> 


Da forma como está, já é possível verificar se está tudo OK. O 
Spring Boot, ao detectar esses componentes, configura o H2 para 
inicializar em memória com um banco chamado testdb , com 
um usuario sa e sem senha. O Spring Boot DevTools 
disponibiliza uma interface de gerenciamento do H2 chamado H2 
console. Inicialize o projeto e abra no seu browser a URL 
http://localhost:8080/h2-console/ para ver a seguinte tela: 





























[English vw] Preferences Tools Help 
Saved Settings: | Generic H2 (Embedded) x4 
Setting Name: Generic H2 (Embedded) “| Save || Remove | 
Driver Class:  [org.n2.Driver á 
JDBC URL: \jdbc:h2:mem:testdb 
User Name: Isa = | 
Password: 

| Connect | |Test Connection | 














Figura 1.7: Tela de login do H2 Console 


Certifique-se de que as configurações estejam como adiante: 


e Driver Class: org.h2.Driver 
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e JDBC URL: jdbc:h2:mem:testdb 
e User Name: sa 
e Password: (em branco) 


Ao clicar em Connect , você deve ver uma tela semelhante a 
seguinte: 


ot | & |2 Auto commit SO “0 | Maxrows:(1000 v| O O E | = |Autocomplete [Of v | Auto select [On v| ®© 





{J jdbc:h2:mem:testdb [Run | Run Selected || Auto complete| Clear) SQL statement: 
E DRIVER 

[3 INFORMATION SCHEMA 

ij) Users 

@ H2 14.199 (2019-03-13) 























Important Commands 
® | (Displays this Help Page 
2 | | Shows the Command History 
= ME one ienai ma “E 
(O |Ctr+Enter | Executes the current SQL statement 
a | Shift+Enter Executes the SQL statement defined by the text selection 
|Ctri+Space |Auto complete 
w | [Disconnects from the database 
Sample SQL Script 
Delete the table ifitexists [DROP TABLE IF EXISTS TEST, 
Create a new table CREATE TABLE TEST(ID INT PRIMARY KEY, 
with ID and NAME columns| NAME VARCHAR(255)); 
Add a new row INSERT INTO TEST VALUES(1, 'Hello'); 
Add another row [INSERT INTO TEST VALUES(2, World"); 
Query the table SELECT * FROM TEST ORDER BY ID; 
Change data in a row [UPDATE TEST SET NAME='Hi' WHERE ID=1; 
Remove a row DELETE FROM TEST WHERE ID=2; 
Help HELP... 
Adding Database Drivers 
Additional database drivers can be registered by adding the Jar file location of the driver to the environmen 
C:/Programs/hsqldb/lib/hsqldb.jar. 


Figura 1.8: H2 Console 


Observe que uma tabela chamada Driver já está criada. Se 
você clicar no botão + ao lado do nome da tabela, vai ver que os 
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campos que mapeamos anteriormente também já estão criados: 


(3 jdbc:h2:mem:testdb 

E E DRIVER 

ID 

BIRTH DATE 

NAME 

13 Indexes 

+ INFORMATION_SCHEMA 
E (9) Users 

(1) H2 1.4.199 (2019-03-13) 





+ 











cu oo e 








+ 
F] 
+ 





























Figura 1.9: Tabela Driver criada 


Verificamos, assim, que nossa infraestrutura já está pronta. 
Ótimo! Só resta mesmo o serviço REST. 


Para criar o serviço, vamos criar um novo pacote no projeto, 
chamado interfaces (observe que o nome está no plural, para 
não conflitar com a palavra inteface , que é reservada no Java). 
Ele vai ficar no mesmo nível do pacote domain . Dentro dele, 
vamos criar uma classe chamada DriverAPI : 
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y Ex capo1 
» Es domain 
Y interfaces 
© DriverAPI 
‘@ Cap01Application 
vy P resources 
Sm static 
© templates 
§application.properties 
» Bi test 
» B target 
= HELP.md 
= mvnw 
= mvnw.cmd 
pom.xml 
É cap01.zip 
> lilli External Libraries 
» "5 Scratches and Consoles 


Figura 1.10: Classe Driver API criada 


Dentro desta classe, vamos criar um método que nos devolva 
todos os motoristas cadastrados no repositório. Este método vai se 
chamar listDrivers , vai retornar uma List com objetos do 
tipo Driver e não vai ter parâmetro algum: 
package app.car.cap01. interfaces; 
import app.car.cap01.domain.Driver; 
import java.util.ArrayList; 


import java.util.List; 


public class DriverAPI { 
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public List<Driver> listDrivers() { 
return new ArrayList<>(); 


} 


Para que esta classe seja reconhecida pelo Spring como um 
serviço REST, é necessário que ela esteja anotada com @Service 
e @RestController : 


import org.springframework.stereotype.Service; 
import org.springframework.web.bind.annotation.RestController; 


@Service 
@RestController 
public class DriverAPI { 
// Restante do código omitido 

Agora, precisamos de alguma forma expor esta informação 
para o mundo. Para fazer isso, precisamos utilizar um método 
HTTP qualquer. É aí que começam a entrar os conceitos de REST, 


mas quais são os métodos, e como escolher? 


1.3 QUAIS SÃO OS MÉTODOS HTTP E COMO 
ESCOLHER ENTRE ELES? 


O protocolo HTTP disponibiliza, até o momento, nove 
métodos HTTP (sendo que sete deles podem ser utilizados em 
REST). Cada um tem a função de nos fornecer uma forma de 
interação com o servidor (de acordo com nossa 
intenção/necessidade); e destes sete, são cinco os principais, que 
podem ser relacionados com operações semelhantes à interação 
com um banco de dados. São os seguintes: 


e GET - para recuperação de dados 
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e POST - para criação de dados 
e PUT e PATCH -para atualização de dados 
e DELETE - para apagar dados 


Observe, no entanto, que esta é uma aproximação muito 
simplista, que utilizo aqui apenas para fins didáticos. Vou entrar 
em mais detalhes a respeito dos métodos HTTP e sua utilização no 
capítulo 2. 


Como queremos listar os dados dos motoristas, vamos utilizar 
o método GET . É possível fazer isso em Spring com a anotação 
GetMapping : 


import org.springframework.web.bind.annotation.GetMapping; 


@Service 
@RestController 
public class DriverAPI { 


@GetMapping 

public List<Driver> listDrivers() { 
// Restante do código omitido 

O próximo passo é determinar qual será o tipo de mídia 
retornado por esta API. Existem vários tipos de mídia disponíveis, 
mas geralmente essa é uma decisão fácil de se tomar pois cada uma 
delas tem um tipo específico. No nosso caso, desejamos servir os 
dados dos motoristas em questão - traduzindo, precisamos servir 
informações estruturadas, de forma que a API se comporte como 
se fosse um catálogo. Temos duas linguagens principais para fazer 
isso: XML ( extensible Markup Language , ou linguagem de 
marcação extensível) e JSON ( JavaScript Object Notation , 
ou notação de objetos JavaScript). Acontece que, de ambas, JSON 
foi a que se tornou a língua franca para servir dados estruturados 
em serviços REST, o que facilita muito a escolha. Isso se deve em 
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grande parte ao tamanho de payloads equivalentes, que é maior em 
arquivos XML que usam muitas tags - dessa forma, onerando redes 
mais limitadas, como as redes móveis. 


Para informar o sistema do Spring de que esta API deverá 
produzir dados em JSON, utilizamos a anotação 
@RequestMapping , junto do parâmetro produces . Este 
parâmetro recebe uma lista de Strings como dados, mas as strings 
aceitas estão populadas como constantes na classe MediaType do 
Spring. O valor a ser utilizado para quando desejamos utilizar 
JSON é APPLICATION JSON VALUE , de forma que a classe fica 
assim: 


import org.springframework.http.MediaType; 

import org.springframework.stereotype.Service; 

import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.RestController; 


@Service 

@RestController 

@RequestMapping(produces = MediaType.APPLICATION_JSON_VALUE) 
public class DriverAPI { 

// Restante do código omitido 


Por último, precisamos informar ao Spring qual URL vamos 
utilizar para mapear esse recurso. Esse é um passo muito 
importante, pois em REST cada recurso tem a sua própria URL e 
esta deve ser significativa, de forma a estimular a usabilidade destes 
serviços. Uma vez que estamos listando instâncias da classe 

Driver , vamos adotar a URL /drivers. 
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Usar As URLS NO SINGULAR OU PLURAL? 


Este é um assunto sobre o qual não existe definição formal 
(ou mesmo informal). Você pode definir suas URLs no 
singular (no nosso exemplo, seria /driver ) ou no plural 
( /drivers ). O único consenso a esse respeito existente na 
comunidade é que deve haver um padrão para todas as APIs 
de um mesmo sistema, ou seja, todas no singular ou todas no 


plural. 





Para mapear essa listagem usando a URL, basta colocá-la como 
String na anotação @GetMapping : 
@GetMapping("/drivers") 


public List<Driver> listDrivers() { 
return new ArrayList<>(); 


} 


Agora, basta inicializar o sistema e navegar para a URL 
http://localhost:8080/drivers . Vocé deve ver em seu 
browser o seguinte: 


[] 


Esta é uma lista vazia em JSON. Note que é a representação do 
que está no método listDrivers , ou seja, no retorno dele está 
mesmo uma ArrayList vazia. Tudo o que temos a fazer agora é 
que a classe DriverAPI tenha acesso à interface 

DriverRepository . O Spring é especializado nisto - como a 
DriverAPI está anotada com @Service , basta que nós façamos 
a inclusão da DriverRepository como um campo da 
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DriverAPI e anotemos este campo com @Autowired : 
package app.car.cap01.interfaces; 


import app.car.cap01.domain.Driver; 

import app.car.cap01.domain.DriverRepository; 

import java.util.ArrayList; 

import java.util.List; 

import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.http.MediaType; 

import org.springframework.stereotype.Service; 

import org.springframework.web.bind.annotation.GetMapping; 
import org.springframework.web.bind.annotation.RequestMapping; 
import org.springframework.web.bind.annotation.RestController; 


@Service 

@RestController 

@RequestMapping(produces = MediaType.APPLICATION JSON VALUE) 
public class DriverAPI { 


@Autowired 
DriverRepository driverRepository; 


@GetMapping("/drivers") 
public List<Driver> listDrivers() { 
return new ArrayList<>(); 


} 


Precisamos então utilizar o DriverRepository para retornar 
os dados do banco de dados, o que é feito através do método 
findAll . O método modificado fica assim: 
@GetMapping("/drivers") 


public List<Driver> listDrivers() { 
return driverRepository.findAll(); 


} 


Ao reinicializar o projeto, o resultado produzido pela URL 
/drivers continua igual. Mas agora, ele está vinculado ao 
conteúdo do banco de dados. Vamos acessar o H2 Console para 
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popular alguns dados no sistema. Ao entrar, eu digito o seguinte: 


INSERT INTO DRIVER(ID, BIRTH_DATE, NAME) 
VALUES (1, '1986-08-18', ‘Alexandre Saudate' ) 


Ao clicar em Run ,a parte de baixo do H2 Console muda e fica 
com o seguinte texto: 
INSERT INTO DRIVER(ID, BIRTH DATE, NAME) 
VALUES (1, '1986-08-18', 'Alexandre Saudate'); 
Update count: 1 
(1 ms) 

A linha que diz Update count: 1 diz que uma linha foi 
atualizada (neste caso, criada). Agora, ao voltar para o browser e 
atualizar a página, devo visualizar algo semelhante ao seguinte: 


{ 

“ig? ds 

“name”: “Alexandre Saudate", 

"birthDate": "1986-08-18703:00:00.000+0000" 
} 


Figura 1.11: Dados sendo retornados da API 


Vamos inserir mais um registro para verificar o retorno em 
lista. Para isso, utilize o seguinte: 


INSERT INTO DRIVER(ID, BIRTH DATE, NAME) 
VALUES (2, '1981-06-03', 'MCLOVIN') 


Ao atualizar o browser, agora visualizamos algo como o 
seguinte: 


[ 


"id: 1; 
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"name": "Alexandre Saudate", 
"birthDate": "1986-08-18T03:00:00.000+0000" 


+, 
{ 
vigia 2, 
"name": "MCLOVIN", 
"birthDate": "1981-06-03T03:00:00.000+0000" 
} 
] 
Conclusão 


Neste capítulo, você viu como criar um projeto com Spring 
Boot (utilizando Spring Initializr), como utilizar as ferramentas do 
Spring Boot para criar um banco de dados em memória, popular 
esse banco e servir os dados em uma API REST. Ainda há muito o 
que ser feito - não vimos como criar estes dados através de uma 
API REST, nem quais métodos podemos utilizar com esse 
propósito. Ou seja, ainda há muito a ser visto. Vamos em frente? 
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CAPÍTULO 2 


EXPANDINDO NOSSO 
SERVIÇO INICIAL 


“Sorte é o que acontece quando a preparação encontra a 
oportunidade” - Sêneca 


Nosso primeiro serviço está funcionando, e já é interoperável. 
Mas não é muito funcional - precisamos de uma forma de permitir 
a recuperação dos dados de apenas um motorista (afinal de contas, 
queremos ter muitos, certo?), também o cadastro e atualização dos 
dados. Temos muito por onde seguir. 


2.1 RECUPERANDO OS DADOS DE UM 
MOTORISTA ESPECÍFICO 


Vamos revisitar por um momento a URL utilizada para 
listagem dos motoristas. A URL foi /drivers , ou seja, uma 
palavra no plural para indicar uma coleção de dados. Em REST, o 
nome que se dá às informações trafegadas é recurso. Quando nós 
fizemos a definição da URL e do tipo de mídia (JSON), nós 
criamos uma definição de um recurso. 


Acontece que as definições de recursos são hierárquicas. 
Espera-se que um motorista em particular esteja contido nesta 
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lista, e esta lista é um recurso por si próprio. Se quisermos criar um 
serviço para recuperar os dados de um motorista em particular, 
devemos criar um novo recurso - desta vez, hierarquicamente 
dependente de /drivers . Se para criar recursos utilizamos URLs 
e um motorista diferente é um recurso diferente (porém 
subordinado ao recurso "pai" que é a listagem de motoristas), então 
precisamos estender a URL /drivers com algo que possa 
identificar de maneira única o motorista específico. Vamos 
revisitar a listagem de motoristas que foi retornada anteriormente: 


[ 


{ 

"id": 1, 

"name": "Alexandre Saudate", 

"birthDate": "1986-08-18T03:00:00.000+0000" 
}, 
{ 

vigd": 2, 

"name": "MCLOVIN", 

"birthDate": "1981-06-03T03:00:00.000+0000" 
} 


Observe que o campo id pode ser utilizado para esse fim! 
Mas ainda existe um problema: o campo id é dinâmico, novos 
IDs vão sendo criados conforme os dados são populados no 
servidor. Logo, não existe um número determinado de IDs, eles 
serão modificados o tempo todo. 


Para resolver esse problema, em REST temos o conceito de 
path parameters: parâmetros que são colocados na própria URL. 
Desta forma, podemos dizer que a URL do nosso novo recurso 
seria algo como /drivers/{id} , onde o valor que está entre 
chaves é nossa variável. 


Para expressar essa mudança, vamos criar um novo método na 
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nossa classe DriverAPI que localiza o motorista especifico: 


@GetMapping("/drivers/{id}") 
public Driver findDriver(){ 

Agora, precisamos vincular algo ao id . Como vamos utilizar 
o ID do banco de dados para também representar o id dos 
nossos recursos, temos que utilizar o mesmo tipo, Long . Por 
último, temos que vincular o texto {id} ao parâmetro, o que é 
feito utilizando-se a anotação @PathVariable : 


import org.springframework.web.bind.annotation.PathVariable; 
// Restante do código omitido... 


@GetMapping("/drivers/{id}") 
public Driver findDriver(@PathVariable("id") Long id){ 
Th as 


} 


Agora, só resta mesmo recuperar o motorista específico, 
utilizando o método findById do repositório. Note, no entanto, 
que este método retorna um java.util.Optional , e não um 
Driver . Para recuperarmos o Driver presente no Optional, 
utilizamos na sequência o método get() : 
@GetMapping("/drivers/{id}") 


public Driver findDriver(@PathVariable("id") Long id){ 
return driverRepository.findById(id).get(); 


} 


Para testar o resultado, precisamos inicializar novamente nosso 
programa, entrar no H2 Console e reinserir os dados. Utilize o 
seguinte SQL: 

INSERT INTO DRIVER(ID, BIRTH_DATE, NAME) 
VALUES (1, '1986-08-18', 'Alexandre Saudate'); 


INSERT INTO DRIVER(ID, BIRTH_DATE, NAME) 
VALUES (2, '1981-06-03', 'MCLOVIN'); 
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Feito isto, navegue para as URLs correspondentes para 
verificar o resultado; primeiro, para 
http://localhost :8080/drivers/1 : 


{ 

tig": 2, 

"name": "Alexandre Saudate", 

"birthDate": "1986-08-18T03:00:00.000+0000" 
} 

E depois para http://localhost :8080/drivers/2 : 
{ 

"id": 2; 

"name": "MCLOVIN", 

"birthDate": "1981-06-03T03:00:00.000+0000" 
} 


2.2 CONHECENDO OS CODIGOS DE STATUS 


O servico esta funcionando para os casos basicos, ou seja, para 
recursos que existem no sistema (os motoristas 1 e 2). Mas e 
quanto a motoristas que nao existem? Se vocé navegar até a URL 

http://localhost:8080/drivers/3 , por exemplo, verá o 
seguinte: 
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Whitelabel Error Page 


This application has no explicit mapping for /error, so you are seeing this as a fallback. 


Sum Nov 03 14:34:27 BRST 2019 

There was an unexpected error (type=Internal Server Errar, status=54X)). 
No value present 

java.util NoSuchElementException: No value present 


at java util Optional.get( Optional. java: 135) 

at app.car.cup02 interfaces, Driver APL findDriver(Driver APL java:30) 

at sunteflect.NativeMethodAccessor!mpl invoked Native Method) 

at sun reflect. NativeMethodAccessorimp! invoke(NativeMethodAccessorimpl java:62) 

at sunreflect. Delegating MethodAccessorImpl invoke(Delegating MethodAccessorlmp! javar43) 

at java lang. reflect. Method. Invoke(Method.java;498) 

at org springframework.web.method support. InvocableHandlerMethod.doInvoke(InvocableHandlerMethod java: 190) 

at ong springframework.web method .support.InvocableHandierMethod, invokeForRequest(InvocableHandierMethod. java: 138) 
at org.springframework.web.serviet. mvc.method.annotation. ServietinvocableHandlerMethod.invokeAndHandle(ServietinvocableHandlerMethod, java: 106) 
at ony springframework web. servletmve method. annotation. Reques MappingHandler Adapter. invoke HandlerMethod( Request MappingHandler Adapter java:B88) 
at org.springframework.web,serviet, mve,method.annotatton. RequestMapping HandlerAdapter-handleIntemal( RequestMapping Handler Adapter java:793) 
at org.springframework.web.serviet.mvc.method.A bstractHandlerMethod Adapter handle( AbstractHandlerMethod Adapter java:87) 
at org.springframework.web,serviet, DispatcherServlet.doDispatch(DisparcherServier,java:1040) 

at org springframework web.servict DispatcherServletdoService(DispatcherServiet java:943) 

at org,springframework.web.serviet.FrameworkServiet.processRequest( FrameworkServlet.java: 1006) 

at org.springframework.web.serviet. FrameworkServiet.doGet(FrameworkServiet.java:898) 

at javax.serviet. http. HupServiet. service( HutpServlet_java:634) 

at org.springframework.web.serviet. FrameworkServiet.service(FrameworkServiet java:883) 

at javax.serviet. http. HapServiet.service(HupServiet java:741) 

at org.apache.catalina.core.ApplicationFilterChain. internal DoF ilter(ApplicationFilterChain.java:231) 

at org apache catalina core. ApplicationFilterChain.doFilter( ApplicationFilterChain java: 166) 

at org apache.tomcat websocket server. WsFilter.doFilter(WsFilter juva:53) 

at org.apache.catalina.core.ApplicationFilterChain. internal DoFilter( A pplicationFilterChain.juva;193) 

at omg apache catalina.core. ApplicationFiterChain.doFilter( ApplicationFilterChain. java:166) 

at org springframework web filter. RequestContexiFilter.doFilterintermal(RequestContextFilter java: 100) 

at org springframework web.filter. OncePerRequestFilter.doFilter(OncePerRequestFilter java: 119) 

at org apache .catalina.core.ApplicationFiherChain internalDoFiher( ApplicationFilterChain.java:193) 

at org apache .catalina core. ApplicationFilterChain.doFilter( ApplicationFilterChain java:166) 

at on springframework web. filter. FormContemFilter.doFilter Internal(FormContenmFilter java:93) 

at org springframework. web. filter, OncePerRequestFilter.doF ilter{ OncePerRequestFilter,java: 119) 

at ong apache catalina.core. A pplicationFiterChain, internal DoP ilter{ ApplicationFilterChain.java:193) 

at org apache .catalina.core, ApplicationFilterChain,dorilter( A pplicationFilterChain. java: 166) 

at org springframework web.filter.CharacterEncodingFilter.doFilterimtemal(CharacterEncodingFlter.java:201) 

at org. springframework.web filter. OncePerRequestFilter doFilter(OncePerRequestFllter.java:119) 

at org apache. catalina.core.AppticationFilterChain.internalDoFilter{ A pplicationFilterChain java: 193) 

at ong.apache.catalina.core.ApplicationFilterChain.doFilter( ApplicationFilterChain. java: 166) 

at ont apache.catalina.core Standard Wrapper Valve.invoke(StandardWrapper Valve. java:202) 

at org apache.catalina.core,StandardContext Valve. invoke( StandardContext Valve, java:96) 

at org apache catalina authenticator. AuthenticarorBase Invoke AuthenticatorBase.java:526) 

at org apache.catalina.core.StandardHostValve invoke(StandardiHost Valve java: 139) 

atorg apache.catalina.valves. ErrorRepon Valve. Invoke(ErrorReponValve.Java;92) 

at org apache. catalina core StandardEngine Valve. invoke(StandardEngineValve.java:74) 


Figura 2.1: Dados sendo retornados da API 


Observe especificamente a linha: 


There was an unexpected error (type=Internal Server Error, status 
=500). 


O protocolo HTTP define alguns tipos de códigos de status, 


cada um condicionado a uma hierarquia diferente. As hierarquias 


são as seguintes: 
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e Os que começam com 1 (lxx) são informacionais - 
mostram ao cliente que a requisição foi recebida e que algo 
está sendo executado. Geralmente não são muito utilizados. 

e Os que começam com 2 (2xx) são códigos de sucesso - 
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mostram ao cliente que a requisição finalizou seu 
processamento com sucesso. O código 200 é uma resposta 
genérica de sucesso, e os outros propõem ao cliente que 
este faça nossos tratamentos mais complexos. 

e Os que começam com 3 (3xx) são códigos de 
redirecionamento - mostram ao cliente que o resultado 
final da requisição depende de outras ações. 

e Os que começam com 4 (4xx) são códigos de falha que foi 
originada por algo de errado que o cliente fez (como erros 
de validação, por exemplo). 

e Os que começam com 5 (5xx) são códigos de falha que foi 
originada por uma condição não tratada pelo servidor. 


Conforme a narrativa deste livro for evoluindo, veremos os 
códigos necessários para realizarmos os tratamentos. Por ora, 
vamos nos ater ao problema que temos em mãos: nosso serviço 
retornou, para o caso de não haver o motorista 3, o código 500. 
Observe que a descrição deste status é Internal Server Error , 
ou Erro interno do servidor, indicando que o servidor não tratou 
corretamente a execução do método get() no caso de o 
Optional não conter valor algum armazenado dentro dele. 


Observe o contexto como um todo: ao passar uma requisição 
para um recurso inexistente, o cliente provocou um defeito no 
servidor. Isso deveria ser tratado como uma falha originada pelo 
cliente. Por isso, vamos utilizar uma anotação mais condizente 
com esse caso - a 404 , que tem o descritivo Not Found , ou Não 
Encontrado. Este código de status foi criado justamente para esse 
cenário, então não há código mais apropriado do que este. 


Para adaptar o código, vamos usar uma facilidade da classe 
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Optional que é o método orElseThrow() . Este método recebe 
como parâmetro uma função lambda que retorna uma exceção, 
que é a que vamos lançar. O Spring fornece uma exceção especial 
para casos como o nosso, a ResponseStatusException . Ela 
recebe como parâmetro um dos valores presentes no enum 

HttpStatus , que contém uma lista dos códigos de status aceitos 
oficialmente pelo protocolo HTTP. Assim sendo, podemos 
modificar nosso código para ficar da seguinte forma: 


import org.springframework.http.HttpStatus; 
import org.springframework.web.server .ResponseStatusException; 
// 


@GetMapping("/drivers/{id}") 
public Driver findDriver(@PathVariable("id") Long id){ 


return driverRepository.findById(id).orElseThrow(() -> new Res 
ponseStatusException(HttpStatus.NOT FOUND)); 
} 


Assim, ao realizar o teste de inicializar nosso projeto e acessar 
novamente a URL http://localhost:8080/drivers/3 , vemos 
o seguinte: 


Whitelabel Error Page 


This application has no explicit mapping for /error, so you are seeing this as a fallback. 


Sun Nov 03 21:41:25 BRST 2019 
There was an unexpected error (type=Not Found, status=404). 
404 NOT_FOUND 
org.springframework.web.server.ResponseStatusException: 404 NOT FOUND 
at app.car.cap02.interfaces.DriverAPI.lambdaSfindDriverSO(DriverAPL.java:32) 
at java.util.Optional.orElseThrow(Optional.java:290) 
at app.car.cap02.interfaces.DriverAPI.findDriver(DriverAPI.java:32) 
at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) 
at sun.reflect.NativeMethod AccessorImpl.invoke(NativeMethodAccessorImpl.java:62) 


Figura 2.2: Código 404 sendo retornado da API 


Como você pode observar, essa página de erro agora contém 
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no miolo o seguinte status: 


There was an unexpected error (type=Not Found, status=404). 
404 NOT FOUND 


2.3 UTILIZANDO UM CLIENTE ADEQUADO - 
INTRODUÇÃO AO POSTMAN 


Para utilizar APIs, precisamos utilizar um cliente que seja 
adequado para controlarmos a passagem de informações para o 
servidor e ver o que está sendo retornado - afinal, precisamos 
também controlar os dados que serão fornecidos para os 
programas que vamos escrever, que vão consumir APIs REST. 
Gostaria de introduzir aqui uma das ferramentas mais difundidas e 
utilizadas para lidar com estas APIs, o Postman, que está 
disponível em https://www.getpostman.com/. Uma vez instalado e 
executado, você deve ver uma tela semelhante à seguinte: 


APis don't sleep either 





Recent workspaces 


Jon a team workspace 


Figura 2.3: Tela inicial do Postman 
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Vamos agora utilizar o Postman para criar as mesmas 
requisições que fizemos via browser. Para isso, clique no botão 
New que fica no canto superior à esquerda: 





Create New x 


| 
‘ial 
Request æ Collection Environment 
Ea [= 
| API Documentation Mock Server Monitor 
| |i = An 
API 
a 
ee 


Figura 2.4: Criando request inicial no Postman 


Clique no botão Request . Ao fazer isso, você deve observar o 
seguinte: 
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Requests in Postman are saved in collections (a group of requests) 


Learn more about creating collection 


Request name 


Request description (Optional) 


Descriptions support lv 


Select a collection or folder to save to 


Q 


Create Collectios 








Figura 2.5: Salvando a request inicial no Postman 


Nesta tela, preencha o campo Request Name com o valor 
listar motoristas e no campo Select a collection or 
folder to save to , digite CAR e depois clique no botão 
Create Collection "CAR" . Na sequência, clique no botão Save 
to CAR . A tela deve ficar assim: 
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Figura 2.6: Salvando a request inicial no Postman 





Finalmente, no campo onde está escrito Enter request URL, 
motoristas, 


coloque a URL da API de listar todos 


Os 


http://localhost:8080/drivers . Feito isto, clique em Send . 
Vocé deve ver uma tela semelhante a seguinte: 


> listar motoristas 


GET 


Params 


Query Params 


No Environment 





ER comments (0) 


aa ~“ 


http://localhost:8080/drivers 


m 


VALUE DESCRIPTION 


is: 2000K Time: 83ms Siz 


BETA SON + 5 


si: 3; 
"name": “Alexandre Saudate", 
“birthDate": "1986-08-18T03:00:00.000+0000" 


"id": 2, 
"name": "McLOVIN", 
"birthDate": "1981-06-03703:00:00.000+0000" 


Figura 2.7: Primeira listagem com Postman 


2658 


+ o 


Examples (0) + 


Cookies Code 


Bulk Edit 


Save Response » 
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Como você pode observar, o conteúdo continua aparecendo. 
Desta vez, é possível ler um campo chamado Status , no centro e 
à direita, com o valor 200 OK . Este é o código de status da 
resposta dada pela API, uma resposta genérica de sucesso. 


Vamos agora testar pelo Postman um retorno com o código 
404 . Altere a URL para http://localhost:8080/drivers/3 e 
aperte Send . Uma resposta como a seguinte pode ser visualizada: 


No Environment X o 
GET listar motoristas e+e a 
+ listar motoristas E comments(0) Examples(o) + 
ser EEE TE 
Headers (7) Cookies Code 
v Headers (0) 
Key VALUE DESCRIPTION eee BulkEdit Presets » 
+ Temporary Headers (7) O 
Body (3) Status: 404 Not Found Time: 35ms Size: 5.14KB Save Response v 
Pretty BETA SON + 53 ma 
4 1 
"timestamp": "2019-11-04701:25:07.136+0000", 


"status": 404, 

"error": "Not Found", 

"message": "494 NOT FOUND", 

"trace": “org.springframework.web. server. ResponseStatusException: 404 NOT FOUND\n\tat 
app.car.cap62. interfaces.DriverAPI. lambda$findDriver$@(DriverAPI.java:32)\n\tat java-util.Optional.orElseThrow 
(Optional. java:296)\n\tat app.car.cap02. interfaces .DriverAPI.findDriver(DriverAPI.java:32)\n\tat 
sun. reflect .NativeMethodAccessorImpl.invoke@(Native Method)\n\tat sun.reflect.NativeMethodaccessorImpl. invoke 
(NativeMethodaccessorImpl. java:62)\n\tat sun. reflect. DelegatingMethodAccessorimpl. invoke 
(DelegatingMethodaccessorImpl. java:43)initat java.lang. reflect .Method. invoke(Method.java:498)\n\tat 
org. springframework.web.method. support . InvocableHandLerMethod . doInvoke( InvocableHandlerMethod. java: 190) \n\tat 
org.springframework.web.method. support . InvocableHandlerMethod. invokeForRequest (InvocableHandlerMethod. java: 138) 
\n\tat org.springframework.web.servlet .mvc .method .annotation.ServletInvocableHandlerMethod. invokeAndHandle 
(ServletInvocableHandlerMethod. java: 106)\n\tat 
org.springframework.web.servlet.mvc.method. annotation.RequestMappingHandlerAdapter . invokeHandlerMethod 
(RequestMappingHandlerAdapter. java:888)\n\tat 


narn enrinnframewark wah carviet mir mathnd annotatinn RaniiactManninntandlarAdanter handlaTnternal 


nu RWNE 


Figura 2.8: Status 404 visto com Postman 


Agora, o campo Status mostra o texto 404 Not Found , ou 
seja, o código 404 continua se fazendo presente. Além disso, você 
pode observar uma outra mudança: o corpo da resposta agora é 
um JSON, diferentemente de quando consultamos utilizando o 
browser. Por que isso acontece? 
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2.4 NEGOCIACAO DE CONTEUDO 


Se você reparar bem, verá que pouco abaixo do campo onde é 
inserida a URL do recurso existe um campo chamado Headers : 


GET -  http://ocalhost:8080/drivers/3 


Params (9) 


Figura 2.9: Existem vários campos abaixo da URL, incluindo um chamado Headers 


Ao clicar nesse botão, aparece uma seção chamada Headers 
com o número 0 e, ao lado, uma seção chamada Temporary 
Headers com o número 7. Ao expandir a seção Temporary 
Headers , vemos o seguinte: 


GET >  http://localhost:8080/drivers/3 


Headers (7) 
» Headers (0) 


KEY VALUE DESCRIPTION 


* Temporary Headers (7) O 


KEY VALUE 


Figura 2.10: Seção de temporary headers expandida 


Essa é a seção de cabeçalhos (ou headers ) que são enviados 
para o servidor no momento da requisição. Na coluna Key existe 
um cabeçalho chamado Accept , que está com o valor */* . Este 
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cabeçalho é um “pedido” para o servidor enviar o tipo de 
informação que está destacada no valor; */* significa que o 
cliente aceita literalmente qualquer coisa. Pode ser uma imagem, 
HTML, um PDF, XML, JSON... 


Como fazemos isso, o nosso serviço no Spring Boot acaba 
escolhendo o melhor tipo de informação a enviar, isto é, um JSON 
descrevendo o problema. No entanto, o browser envia algo muito 
diferente. O valor exato que é enviado pode variar, mas o que 
capturei no Google Chrome versão 74.0.3729.108, rodando em um 
Ubuntu Linux 18.04.2, foi o seguinte: 

text/html, application/xhtml+xml, application/xml; q=0.9, 
image/webp, image/apng, */*;q=0.8,application/signed- 
exchange;v=b3 . Quando este valor é enviado, o servidor 
interpreta que o melhor formato a ser utilizado no envio das 
informações éo text/html, um HTML. Mas como essa seleção é 
feita? 


O primeiro passo é segmentar os dados. Observe que existe 
uma vírgula separando os valores e, se retirarmos esta vírgula, 
vamos enxergar o seguinte: 


e text/html 

e application/xhtml+xml 
e application/xml;q=0.9 
e image/webp 

e image/apng 

e */*;q=0.8 


e application/signed-exchange; v=b3 


Estes valores são chamados de MIME Types , ou 
alternativamente, Media Types (lembra-se de quando utilizamos 
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a anotação @RequestMapping na nossa API?). Cada um desses 
media types tem uma estrutura assim: <tipo>/<subtipo> . O 
tipo é como se fosse a "familia" das informações, ou seja, texto, 
imagem etc. Um tipo particular é application , que geralmente 
representa dados binários mas pode ser utilizado em texto 
estruturado - JSON, por exemplo. 


A respeito do */* que temos na listagem, acontece o seguinte: 
o * (asterisco) é utilizado como um curinga nos media types. 
Isso quer dizer que, em uma API que serve imagens, eu posso 
utilizar o media type image/* para obter uma imagem genérica 
de qualquer tipo (JPEG, PNG, GIF etc.). Quando o curinga está 
dos dois lados, como apresentado ali em cima, significa "qualquer 
coisa”. O Chrome pediu para o servidor enviar qualquer tipo de 
dado disponível. 


Mas você deve estar se perguntando: "Mas faz sentido enviar 
todos esses dados junto com uma solicitação de ‘qualquer coisa’? 
Por que não enviar somente essa solicitação, já que o servidor vai 
enviar qualquer coisa mesmo?”. Faz sentido enviar essa solicitação 
devido ao parâmetro extra que está acompanhando o */* 
Observe que o media type completo é */*;q=0.8 . O ponto e 
vírgula é usado para separar o media type dos parâmetros, e o 

q é um parâmetro que determina a preferência por esse tipo de 
dado (neste caso, 0.8, em um range que varia de 0.1 até 1.0, sendo 
este último o padrão). Se a preferência por qualquer tipo de dado é 
diminuída, significa que o servidor vai priorizar a ordem de 
entrega dos dados assim: 


e text/html 


e application/xhtml+xml 
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e image/webp 

e image/apng 

e application/signed-exchange 
e application/xml 


e F/R 


Portanto, vai usar o parâmetro q para estabelecer uma ordem 
de prioridade e, depois, por ordem em que os media types 


aparecem. 


Vamos fazer um experimento: insira o cabeçalho Accept 


Postman com o valor text/html, */* e depois aperte Send . 


resposta deve ser semelhante à seguinte: 


GET © — hupyfocathos-sunovdrwerss 
Header 
Headers (1 
mr VALUE 
Bs 
Head o 
nr VALUE 
Body 4 
pretty om um e 5 
1 tah 
2 
3 «body> 
4 <hiswhiteladel Error Page</ni> 
5 <p>This application has no explicit mapping for /error, so you are seeing this as a fallback.</p> 
6 <div ide'created'>Mon Nov 64 16:27:14 BRST 2019</div> 
ediveThere was an unexpected error (typestot Found, statuse404).</dive 
4 «<div>404 NOT FOUND</div> 
9 <div Style~'white-space:pre-wrap; ">org. springframework.web. server. ResponsestatusException: 404 NOT FOUND 
10 at app.car.cap02.interfaces.OriverAPl. lambdasfinddrivers0(OriverAPl.java:42) 
n at java.util Optional .orflseThrowiOptional. java: 290) 
u at epp.car.cap02. interfaces. DriverAPI, findOriver(DriverAPI, java:42) 
LEJ at sun.reflect.NativeMethodAccessorIapt. invokeð(Native Method) 
14 at sun. reflect .NativeMethodAccessor Impl. invoke (Nat iveMethodAccessorIepl . java:62) 
18 at sun reflect .Delegatingmethodaccessor Impl. invoke (DelegatingMethodaccessorImpl. java: 43) 
16 at java. lang. reflect Method. invoke (Method, java:498) 


Figura 2.11: A request retorna HTML quando o cabeçalho Accept muda 
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MAS POR QUE UTILIZAR O TEXT/HTML COM */* ? 


O Spring Boot apresentou este resultado nos meus testes - 


pode considerar como um bug. O correto seria retornar o 


HTML mesmo sem o / no cabeçalho. Veremos a seguir o que 
acontece se não passarmos esse valor. 





Em compensação, colocar neste cabeçalho um media type 
que não é aceito pelo servidor provoca o retorno do status 406 
Not Acceptable . Se colocarmos */* ou application/json , 
ele retorna o JSON que vimos anteriormente. 


Vale observar que, para que o mecanismo de negociação de 
conteúdo funcione, é necessário que o servidor também informe 
qual tipo de conteúdo está sendo servido de fato. Isto porque, caso 
o cliente utilize um curinga (ou mesmo dois, no caso da requisição 
com */* ), é necessário que o servidor avise o que está realmente 
sendo fornecido. Este aviso é feito através do cabeçalho Content- 
Type , que retorna sempre um único media type e sem curinga. 
No nosso caso, a API sempre retorna JSON pois foi o que 
declaramos no cabeçalho @RequestMapping . Alguns capítulos 
adiante veremos como servir outros tipos de conteúdo. 


2.5 ENVIANDO DADOS PARA O SERVIDOR 


Agora que já vimos vários dos aspectos da listagem de 
motoristas, veremos como fazer a criação de dados utilizando a 
API 
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Como você viu no capítulo passado, a criação de dados do lado 
do servidor é feita utilizando o método HTTP Post . Este método 
é especial, pois permite que o usuário utilize o corpo da requisição 
para passar parâmetros, ao contrário do GET , que só permite que 
o servidor envie dados no corpo. 


Vamos modificar nossa API para fazer isso. Primeiro, crie um 
método na classe DriverAPI com a seguinte assinatura: 


public Driver createDriver(Driver driver) 


De maneira semelhante ao método listDrivers , vamos 
anotar nosso método com @PostMapping , indicando para o 
Spring que esse método vai responder ao método POST . Da 
mesma forma, vamos passar como parâmetro a URL /drivers : 


import org.springframework.web.bind.annotation.PostMapping; 
Haas 


@PostMapping("/drivers") 
public Driver createDriver(Driver driver) 
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POR QUE VAMOS USAR A MESMA URL DE ANTES? 


Em REST, a URL de um recurso é apenas um dos aspectos da 
forma como interagimos com ele. Ela representa a dimensão 
da nomenclatura e hierarquia do recurso, mas a forma como 
interagimos com o recurso é determinada pelos métodos 
HTTP. Assim sendo, a URL permanece sendo a mesma 
porque ainda estamos lidando com motoristas. 


Criando uma analogia para melhor compreensão, imagine 
que você tem um par de tênis. Você o compra e o coloca na 
sua sapateira ( POST ). Você o procura para utilizar ( GET ) 
várias vezes. Em alguma dessas vezes, você pode retirá-lo para 
lavar, e devolve um tênis talvez com outras características 
( PATCH ). Um dia, você o vende (ou doa) - DELETE . 


Observe que a interação é com o tênis, mas a forma/intenção 


pode ser diferente. É por isso que utilizamos a mesma URL: 


os recursos permanecem sendo os mesmos; o que muda é a 
forma como lidamos com eles. 





Precisamos também informar ao Spring que o Driver que foi 
passado como parâmetro vai estar presente no corpo da requisição. 
Para isso, utilizamos a anotação @RequestBody : 
import org.springframework.web.bind.annotation.RequestBody; 

Me 


@PostMapping("/drivers") 
public Driver createDriver(@RequestBody Driver driver) 


Finalmente, utilizamos o método save do repositório para 
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salvar o motorista e retornar os dados ja persistidos no banco de 
dados: 


@PostMapping("/drivers") 
public Driver createDriver(@RequestBody Driver driver) { 
return driverRepository.save(driver); 


Agora, vamos realizar os testes da nova API com Postman. Ao 
lado da aba com o nosso método GET (lá onde está escrito 
listar motoristas ), existe um botão de + . Clique nesse botão 
e, na sequência, vá até o dropdown onde está listado o método 
GET e mude para POST . Na parte da URL, coloque a mesma de 
antes, http://localhost:8080/drivers . Então, clique no botão 
Body e no radio onde está escrito raw . Isto quer dizer que o 
corpo da requisição receberá dados brutos. Um dropdown à direita 
apareceu; mude o valor deste para JSON : 


La pad ser r : ow? http:/Mocalhost:8080/drivers @ + ce 


Untitled Request 


POST +  http://localhost:8080/drivers 


Body 


none form-data x-www-form-urlencoded ® raw binary GraphqL BETA Text a 


Text 
JavaScript 
JSON 
HTML 


XML 


Figura 2.12: Configurando o Postman para realizar a requisição 


Vamos preencher agora com dados compatíveis com a 
requisição. Como vimos antes, trata-se de um JSON com os 
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campos name e birthDate : 


{ 


"name" :"Fulano de Tal", 
"birthDate":"1960-01-01" 


Abro um pequeno interlúdio aqui para fazer uma observação: 
clique na seção Headers e você verá que o Postman criou um 
cabeçalho Content-Type e o preencheu com 

application/json . Observe que, quando enviamos dados, 
também precisamos enviar o cabeçalho mencionado com o tipo de 
conteúdo que estamos enviando. Quando selecionamos JSON no 
dropdown, o Postman preencheu esse cabeçalho para nós 
automaticamente. 


Voltando ao nosso teste da requisição, apertamos o botão 
Send agora e recebemos a seguinte resposta: 
"status": 500, 
"error": "Internal Server Error", 
"message": "ids for this class must be manually assigned before c 
alling save(): app.car.cap02.domain.Driver; nested exception is o 
rg.hibernate.id.IdentifierGenerationException: ids for this class 


must be manually assigned before calling save(): app.car.cap02.d 
omain.Driver" 


Isso quer dizer que, quando criamos a nossa classe Driver , 
não oferecemos ao Spring/JPA qualquer indicativo de como 
realizar a geração dos índices no banco de dados. Podemos corrigir 
isso anotando o campo id da classe Driver com 


@GeneratedValue : 
package app.car.cap02.domain; 


// restante dos imports omitidos 
import javax.persistence.GeneratedValue; 
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@Data 
@Entity 
public class Driver { 


@Id 
@GeneratedValue 
Long id; 

String name; 
Date birthDate; 


Reinicie a aplicação e aperte o botão Send novamente. O 
resultado deverá ser o seguinte: 


{ 

"id": 4, 

"name": "Fulano de Tal", 

"birthDate": "1960-01-01T00:00:00.000+0000" 
} 


2.6 IDEMPOTENCIA: OS EFEITOS DE 
INVOCACOES SUCESSIVAS 


Clique no botão Send varias vezes seguidas. Observe que o 
id vai sendo incrementado, ou seja, a cada clique do botão um 
novo recurso é criado no lado do servidor. Este fato levanta uma 
questão muito importante: suponha que você realize o envio de 
uma informação para o servidor, mas quando o servidor está 
enviando a resposta, por algum motivo a conexão criada é perdida. 
Desta forma, você não consegue receber o resultado da invocação e 
não sabe se a requisição teve sucesso ou não. O que fazer: reenviar 
a requisição ou não? 


Existe uma propriedade dos métodos HTTP que é a 
idempotência, que trata a respeito dos efeitos que sucessivas 
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invocações para o servidor terão (da mesma forma que você fez 
clicando várias vezes sobre o botão Send ). Dizemos que uma 
requisição é idempotente quando o efeito da enésima requisição é 
igual ao da primeira. Em outras palavras, não importa quantas 
vezes enviamos uma requisição, nenhuma alteração sobre o estado 
do servidor será produzida, além daquela feita pela primeira, que 
tinha as mesmas características. Obviamente, falamos de um 
servidor isolado, isto é, não há nenhum outro cliente interagindo 
com os mesmos recursos. 


Isso nos permite ter uma segurança quando falamos a respeito 
do cenário em que não recebemos a resposta. Podemos 
simplesmente reenviar a requisição - se o método é idempotente, o 
resultado esperado será o mesmo que a primeira requisição. Isso 
não vale para métodos que não são idempotentes, pois podemos 
criar dados no servidor além daqueles necessários, e criar efeitos 
indesejados. 


Observe também que esta propriedade trata exclusivamente da 
relação entre o cliente e o servidor, em termos de recursos. Por 
exemplo: suponha que eu uso um método idempotente sobre o 
servidor, mas a cada invocação nova um log é gerado do lado do 
servidor. Mesmo assim, a requisição é considerada idempotente 
porque os logs dizem respeito exclusivamente ao comportamento 
interno do servidor, não fazendo parte da relação cliente e 
servidor. 


f 


Nos exemplos que vimos até agora, o método GET é 
idempotentee o POST não. Por esse motivo, inclusive, os browsers 
muitas vezes nos perguntam se queremos reenviar dados: 
eventualmente estamos preenchendo um formulário, ou algo do 
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tipo, e os dados são enviados usando POST . Quando de alguma 
forma solicitamos que a página seja atualizada (apertando o botão 

F5 ou de alguma outra forma), o browser pede que o usuário 
assuma o risco de reenviar os dados, pois isso pode gerar esses 
efeitos colaterais. 


2.7 ATUALIZANDO OS DADOS ENVIADOS 
COM PUT E PATCH 


E por falar em idempotência, temos os casos dos métodos PUT 
e PATCH , que são utilizados para fazer atualizações (portanto, 
escrevem dados) no lado do servidor mas são idempotentes. 


Mas por que temos dois métodos para fazer isso? Porque cada 
um faz a atualização de uma forma. O PUT atualiza o conjunto 
todo; o PATCH , apenas um trecho. Vamos ver rapidamente a 
diferença antes de realizar a implementação. Vamos rever o JSON 
do motoristacomo id 1: 


{ 

vids 1, 

"name": "Fulano de Tal", 

"birthDate": "1960-01-01T00:00:00.000+0000" 
} 


Se nós quisermos realizar uma mudança em todos os dados, é 
melhor utilizar o PUT : 


PUT /drivers/1 


"name": "Alexandre Saudate", 
"birthDate": "1986-08-18" 
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Se eu deixar de enviar um dos dados ( name ou birthDate ), 
o uso do PUT vai fazer com que meu serviço entenda que esses 
dados devem ser descartados. A exceção à regra é o campo id, 
que neste caso é utilizado na URL por dois motivos: o primeiro, 
para ser mais adequado à noção de recurso em REST. Se eu fizesse 
o PUT diretamente sobre a URL /drivers , isso indicaria que 
estamos fazendo a atualização da lista toda de motoristas, o que 
não é o caso. 


O segundo motivo é para melhorar a condição de concorrência 
em que o servidor pode se encontrar. Ao efetuar as atualizações de 
dados sobre um recurso isolado, fica mais fácil de lidar com 
possíveis atualizações concorrentes, em que mais de um usuário 
pode tentar criar ou atualizar dados no mesmo recurso ao mesmo 
tempo. 


Já o método PATCH vai fazer uma mudança apenas 
incremental. Se utilizarmos este método sobre o motorista Fulano 
de Tal , faremos a atualização apenas do campo passado no 
PATCH , veja: 


PATCH /drivers/1 
"name":"Alexandre Saudate" 


Desta forma, o campo birthDate vai permanecer intocado, 
com o mesmo valor de antes da requisição com PATCH . Isto faz 
com que cada um dos recursos possa ser usado nos mesmos 
recursos, sendo um mais interessante do que o outro em alguns 
aspectos. 


Vamos à implementação. Como você já viu, a URL vai ser 
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` 


semelhante à de localização de um motorista específico, 
/drivers/{id} . Já o corpo da requisição vai receber o JSON 

contendo o motorista. Logo, a implementação é como se fosse a 

junção da implementação do método de localizar um motorista 

específico com o método de criar um novo motorista. Desta forma, 

vamos criar a assinatura do método com esses conceitos e a 
anotação @PutMapping , que vai realizar a ligação desse método 
como PUT: 

@PutMapping("/drivers/{id}") 

public Driver fullUpdateDriver(@PathVariable("id") Long id, @Requ 


estBody Driver driver) { 
// implementação... 


} 


Para a implementação do corpo do método em si, vamos fazer 

com que o método fullUpdateDriver chame o método 
findDriver , pois desta forma o método vai automaticamente 

fazer com que o código 404 seja retornado em caso de tentarmos 
fazer a atualização de um motorista inexistente. Vamos também 
fazer a transposição dos dados passados como parâmetro para o 
motorista encontrado e, então, chamar o método save do 
repositório: 
@PutMapping("/drivers/{id}") 
public Driver fullUpdateDriver(@PathVariable("id") Long id, @Requ 
estBody Driver driver) { 

Driver foundDriver = findDriver(id); 

foundDriver.setBirthDate(driver.getBirthDate()); 


foundDriver.setName(driver.getName()); 
return driverRepository.save(foundDriver) ; 


Agora, vamos utilizar novamente o Postman para testar nosso 
método. Crie uma nova requisição no Postman ajustando o 
método HTTP para PUT e a URL para 
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http://localhost:8080/drivers/1 . Quanto ao corpo da 
requisição, ajuste para o seguinte: 


{ 
"name": "Alexandre Saudate", 
"birthDate": "1986-08-18" 
} 
PUT ~  http://ocalhost:8080/drivers/1 


(9) Body @ 
none form-data x-www-form-urlencoded ® raw binary GraphQL BETA ON v 


ar { 
“name”: “Alexandre Saudate”, 
“birthDate”: “1986-08-18” 


Figura 2.13: Realizando a requisição PUT com Postman 


Se tudo estiver certo, você deve receber uma resposta 
semelhante à seguinte: 


{ 

"id": 2, 

"name": "Alexandre Saudate", 

"birthDate": "1986-08-18T00:00:00.000+0000" 
} 


Agora, faça o seguinte teste: retire o campo birthDate da 
requisição de entrada, deixando apenas o nome. Em outras 
palavras, envie o corpo da requisição assim: 


{ 

"name": "Alexandre Saudate", 
} 

O resultado da requisição será o seguinte: 
{ 


ETE 
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"name": "Alexandre Saudate", 
"birthDate": null 


Observe que o campo birthDate ficou nulo. Nós 
implementamos o método PUT levando isso em consideração, já 
que esta é a natureza dele. 


Vamos agora à implementação do método PATCH . A 
assinatura do método na classe DriverAPI fica muito 
semelhante, exceto que agora utilizamos a anotação 
@PatchMapping : 

@PatchMapping("/drivers/{id}") 
public Driver incrementalUpdateDriver (@PathVariable("id") Long id 


, @RequestBody Driver driver) { 
// Implementação... 


} 


A implementação do método também é semelhante. A 
diferença é que vamos testar os campos a serem mapeados para, 
caso passemos algum dado nulo, a implementação considera o que 
já havia antes. Para evitar muita verbosidade na escrita, vamos 
utilizar a classe Optional e seus métodos ofNullable e 
orElse para fazer esses testes: 


@PatchMapping("/drivers/{id}") 
public Driver incrementalUpdateDriver(@PathVariable("id") Long id 
, @RequestBody Driver driver) { 
Driver foundDriver = findDriver(id); 
foundDriver.setBirthDate(Optional.ofNullable(driver.getBirthDa 
te()).orElse(foundDriver.getBirthDate())); 
foundDriver.setName(Optional.ofNullable(driver.getName()).orEl 
se(foundDriver.getName())); 
return driverRepository.save(foundDriver); 


} 


Agora, vamos enviar o JSON do com o método PATCH já sem 
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o campo birthDate : 


PATCH ~  http://localhost:8080/drivers/1 


(9) Body @ 


none form-data x-www-form-urlencoded $ raw binary GraphQL BETA ISON v 


“name”: “Alexandre Saudate” 


Figura 2.14: Realizando a requisição PATCH com Postman 


O resultado deve ser algo como o seguinte JSON: 


{ 

"id": 2, 

"name": "Alexandre Saudate", 

"birthDate": "1960-01-01T00:00:00.000+0000" 
} 


2.8 APAGANDO OS DADOS DE UM 
DETERMINADO MOTORISTA 


Finalmente, para completar o conjunto das operações básicas 

que podemos realizar sobre um recurso, vamos falar do método 

DELETE . Deixei este método por último porque ele apresenta 
algumas polêmicas. 


A primeira polêmica é em relação ao corpo da requisição. A 
especificação formal do método DELETE não deixa claro se é 
permitido ou não enviar dados no corpo, o que pode gerar 
problemas de acordo com a ferramenta utilizada. Algumas 
ferramentas podem aceitar, outras podem rejeitar por completo 
(sem aviso), outras podem retornar um erro HTTP. O Spring Boot, 
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na versão utilizada na escrita deste livro, utiliza um servidor 
Tomcat para servir as requisições. Este servidor suporta corpo para 
o método HTTP DELETE . Eu, no entanto, não recomendo que 
você use devido aos problemas mencionados. 


A segunda polêmica é em relação à idempotência. O método 
DELETE é considerado idempotente porque apenas a primeira 
requisição vai produzir alterações sobre o estado do servidor. As 
requisições subsequentes estarão impossibilitadas de produzir 
alterações porque o recurso já terá sido apagado. No entanto, 
enquanto a resposta da primeira requisição pode ser um 200 , a 
resposta das requisições seguintes pode ser 200 ou 404 (ou seja, 
recurso não encontrado), dependendo da implementação. A 
idempotência, neste caso, é considerada porque não foi produzida 
alteração no estado do servidor, isto é, a primeira requisição 
apagou o recurso e, da segunda em diante, o recurso já não existia 


mais. 


Dito isto, penso o seguinte em relação aos códigos retornados 
da segunda requisição em diante: não há certo ou errado. Depende 
do cenário de uso - se faz sentido para os possíveis clientes da API 
receberem uma resposta de erro em caso de reenvio de uma 
requisição ou não. 


Postas estas considerações, vamos à implementação do método 
no servidor. Assim como os outros métodos HTTP mencionados, 
a implementação do DELETE segue a mesma linha de 
simplicidade. Basta utilizar a anotação @DeleteMapping para 
realizar o mapeamento, e o método deleteById do repositório 
para efetivamente excluir o dado do repositório. O código fica 
assim: 
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@DeleteMapping("/drivers/{id}") 
public void deleteDriver(@PathVariable("id") Long id) { 
driverRepository.deleteById(id); 


Agora, vamos reinicializar o sistema e abrir uma nova aba no 
Postman para fazer o teste da API. Não se esqueça de que, como 
nosso banco está em memória, os dados se perdem quando o 
sistema é reinicializado, então precisamos fazer a criação do 
motorista novamente, com POST . Feito isto, podemos configurar 
o Postman para enviar uma requisição com o método DELETE : 


DELETE + _ http://ocalhost:8080/drivers/1 


Params i (1) b 


Query Params 


KEY VALUE 


Figura 2.15: Realizando a requisição DELETE com Postman 


Ao realizarmos essa requisição, ela retorna o código 200 , o 
que significa que conseguimos apagar com sucesso o registro. É 
possível realizar a verificação utilizando o método GET . 
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COMO FAÇO PARA CRIAR UMA API DE DELETE LÓGICO? 


O delete lógico consiste em ajustar um atributo na 
entidade para que ela esteja desativada apenas, e o recurso 
não seja mais listado com o método GET . Desde que 
realmente não seja mais listado, o mapeamento deve ser feito 
da mesma forma como funciona um delete físico, ou seja, 
utilizando o método HTTP DELETE em conjunto com a URL 
do recurso. 


Será feito de outra forma apenas se o recurso puder voltar a 
ser listado. Por exemplo, se houver alguma forma de trazer o 
recurso apagado logicamente de volta à listagem, então na 
verdade deveria ser utilizado o método PATCH ou PUT. 


Observe que isso muda a forma inclusive de encarar o 


recurso, pois ele passa a ser visto como desativado, e não 
apagado. 





Repare, no entanto, que se tentarmos apagar um motorista que 
não existe (ou que já tenha sido apagado) recebemos o seguinte 
erro: 


"timestamp": "2019-11-08T23:33:48.318+0000", 
"status": 500, 


"error": "Internal Server Error", 

"message": "No class app.car.cap02.domain.Driver entity with 
id 1 exists!", 

etc.. 


Isso ocorre porque nosso recurso nao esta realizando o 
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tratamento adequado a respeito do caso onde o motorista já tenha 
sido apagado. Caso queiramos tratar isso é simples - basta utilizar 
novamente o método findDriver e passar o motorista 
encontrado como parâmetro para o método delete do 
repositório. Caso o motorista não seja encontrado, o método vai 
devolver o status 404 Not Found : 

public void deleteDriver(@PathVariable("id") Long id) { 


driverRepository.delete(findDriver(id)); 


} 


Conclusão 


Neste capítulo, conhecemos melhor alguns outros dos métodos 
HTTP. Conseguimos interagir de forma mais ampla com o 
recurso, realizando criação de novos recursos, atualização e 
apagando. Também conhecemos alguns códigos de status novos e 
tipos de mídia. Aos poucos, estamos conhecendo melhor a 
estrutura de um recurso REST e seus pilares - a forma de modelar 
URLs, quais métodos utilizar, tipos de mídia, códigos de status etc. 


Ainda há recursos poderosos a serem conhecidos, estamos 
apenas começando. Vamos começar a investigar mais 
profundamente os tipos de mídia e a interação dos recursos uns 
com os outros. 
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CapPiTULo 3 


CRIANDO 
RELACIONAMENTOS 
ENTRE RECURSOS 


"O começo é a parte mais importante do trabalho" - Platão 


Agora que já temos uma API para executar as operações de 
motoristas, vamos seguir rumo a conclusao do nosso primeiro caso 
de uso. Precisamos criar mais duas APIs: uma que faça as mesmas 
operações para passageiros (ou seja, um cadastro para eles) e uma 
que receba deles os pedidos de viagens para realizar a interligação 
entre motoristas e passageiros. 


3.1 CRIANDO A API DE PASSAGEIROS 


Como já sabemos criar uma API simples, vamos repetir o 
procedimento para criação de motoristas na plataforma para 
realizar também o cadastro de passageiros. Vamos criar a entidade 
que representa os passageiros da seguinte forma: 


package app.car.cap03. domain; 
import javax.persistence.Entity; 


import javax.persistence.GeneratedValue; 
import javax.persistence.Id; 
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import lombok.Data; 


@Data 
@Entity 
public class Passenger { 


@Id 
@GeneratedValue 
Long id; 

String name; 


Vamos também criar o repositório equivalente: 
package app.car.cap03. domain; 
import org.springframework. data. jpa.repository. JpaRepository; 


public interface PassengerRepository extends JpaRepository<Passen 
ger, Long> {} 


Finalmente, vamos criar a API, baseado no que vimos da API 
de motoristas: 


package app.car.cap03. interfaces; 


import app.car.cap03.domain.Passenger; 

import app.car.cap03.domain.PassengerRepository; 

import java.util.List; 

import java.util.Optional; 

import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.http.HttpStatus; 

import org.springframework.http.MediaType; 

import org.springframework.stereotype.Service; 

import org.springframework.web.bind.annotation.*; 

import org.springframework.web.server .ResponseStatusException; 


@Service 

@RestController 

@RequestMapping(path="/passengers", produces = MediaType.APPLICAT 
ION_JSON_VALUE ) 

public class PassengerAPI { 
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@Autowired 
PassengerRepository passengerRepository; 


@GetMapping() 
public List<Passenger> listPassengers() { 
return passengerRepository.findAll(); 


} 


@GetMapping("/{id}") 
public Passenger findPassenger(@PathVariable("id") Long id) { 
return passengerRepository.findById(id).orElseThrow(() -> 
new ResponseStatusException(HttpStatus.NOT FOUND)); 


} 


@PostMapping 
public Passenger createPassenger(@RequestBody Passenger passe 
nger) { 
return passengerRepository.save(passenger); 


} 


@PutMapping("/{id}") 
public Passenger fullUpdatePassenger(@PathVariable("id") Long 
id, @RequestBody Passenger passenger) { 
Passenger p = findPassenger (id); 
p.setName(passenger.getName()); 
return passengerRepository.save(p); 


} 


@PatchMapping("/{id}") 
public Passenger incrementalUpdatePassenger (@PathVariable("id 
) Long id, @RequestBody Passenger passenger) { 
Passenger foundPassenger = findPassenger (id); 
foundPassenger .setName(Optional.ofNullable(passenger.getN 
ame()).orElse(foundPassenger.getName())); 
return passengerRepository.save(foundPassenger ); 


} 
@DeleteMapping("/{id}") 


public void deletePassenger(@PathVariable("id") Long id) { 
passengerRepository.delete(findPassenger(id)); 


} 


Observe que, nesta API, existe uma pequena diferença em 
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relação à API de motoristas que havíamos criado antes: a anotação 
@RequestMapping já possui o atributo path que, por sua vez, é 
espelhado para todas as anotações de mapeamento REST da classe. 
Isso quer dizer que, onde a URL REST não é mencionada (no 
caso, somente no método listPassengers ), atribui-se a URL 
/passengers a ele. Se a URL for mencionada, então assume-se 
que a URL /passengers vai no começo e o restante, no final. Por 
exemplo, no método  findPassenger , toma-se a URL 
/passengers no começo eo /{id} (proveniente da anotação 

@GetMapping ) no final, sendo que a URL final fica 
/passengers/{id} . 


3.2 CRIANDO A API DE SOLICITACAO DE 
VIAGENS 


A proxima API que temos que criar apresenta um desafio um 
pouco diferente do que vimos anteriormente. Aqui, precisamos 
criar uma API onde seja possivel que um determinado passageiro 
faça uma solicitação de viagem. Neste caso, perceba que não ha 
mais uma simples requisição para um banco de dados sendo feita, 
mas sim uma ação a ser tomada. É aqui onde precisamos começar 
a adotar algumas técnicas específicas de modelagem para não criar 
errado. 


Antes de mais nada, precisamos primeiro conhecer qual é o 
recurso específico com o qual estamos lidando. Pode parecer 
bobagem, mas já vi muitos desenvolvedores experientes errarem 
em modelagem de APIs por não saberem com qual recurso estão 
lidando. Portanto, tenha em vista que, em um primeiro momento, 
estamos lidando com solicitações de viagens, o que é diferente de 
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viagens. O primeiro recurso, ao haver aceite de um motorista, é 
convertido no segundo. 


O primeiro passo é modelar a URL. Pode parecer tentador 
modelar um em função do outro; no entanto, isso é uma 
armadilha. Como já mencionei antes, as URLs dos recursos REST 
são definidas de forma hierárquica. Isso quer dizer que, se 
pegarmos uma URL e separarmos cada porção pela / , as porções 
mais à direita serão encaradas como subconjuntos das porções que 
ficarem mais à esquerda. Por exemplo, o site 

https://restfulapi.net/ , na seção REST Resource Naming 
Guide ( Guia para nomenclatura de recursos REST ), diz o 
seguinte (ja traduzido por mim): 


Um recurso pode conter subcoleções de recursos. Por 
exemplo, o recurso subcoleção "contas" de um "cliente" em 


particular pode ser identificado pela URI 


"/customers/{customerld}/accounts" (em um domínio 
bancário). De forma similar, um recurso singleton "conta" 
dentro do recurso subcoleção "contas" pode ser identificado 
como se segue: 


"/customers/{customerId}/accounts/{accountId}" 





Ou seja, podemos interpretar as URLs como conjuntos, e cada 
um dos trechos seguintes (separados por / ) pode ser interpretado 
como subconjunto do conjunto principal. 


No entanto, no nosso contexto em particular, é um erro 
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considerar que existe tal relação entre as solicitações de viagens e 


as viagens. Vamos analisar o motivo: 


Se modelarmos a URL como /solicitacoes/viagens , 
vamos acabar considerando que todas as viagens 
pertencem de uma vez só a todas as solicitações de viagens, 
o que é um erro; 
Se modelarmos a URL como 
/solicitacoes/{id}/viagens , vamos acabar chegando 
à conclusão de que sempre vamos precisar do ID da 
solicitação de viagem para conseguir chegar à viagem 
ocorrida, o que prejudica a usabilidade da nossa API; 
Se modelarmos a URL como /viagens/solicitacoes , 
temos um problema semelhante ao primeiro caso; 
Se modelarmos a URL como 
/viagens/{id}/solicitacoes , nao vamos conseguir 
criar uma solicitação sem antes ter uma viagem, o que é um 
erro semântico. 


O próximo passo é identificar como seria o recurso de 


solicitação de viagens. Para realizar uma solicitação, precisamos: 


Do passageiro; 
Do local de origem; 
Do local de destino. 


Com estes dados, vamos criar a entidade de solicitação de 


viagens: 


@Data 
@Entity 


public class TravelRequest { 


@Id 
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@GeneratedValue 
Long id; 


@ManyToOne 
Passenger passenger; 
String origin; 
String destination; 


Agora, vamos criar um repositório para esta entidade: 


public interface TravelRequestRepository extends JpaRepository<Tr 
avelRequest, Long> {} 

Finalmente, vamos criar a classe de API. Diferente das outras, 
vamos inicialmente criar apenas uma “casca” desta API, contendo 
apenas a parte de criação do recurso de solicitação de viagem: 
@Service 
@RestController 
@RequestMapping(path = "/travelRequests", produces = MediaType.AP 


PLICATION_JSON_VALUE) 
public class TravelRequestAPI { 


@PostMapping 
public void makeTravelRequest (@RequestBody TravelRequest tra 


velRequest) { 


} 


3.3 CRIACAO DO SERVICO DE SOLICITACAO 
DE VIAGENS 


Como você pôde observar, a API que criamos para fazer as 
solicitações de viagens está vazia. Isso é porque agora temos os 
seguintes passos a realizar: 


e Salvar as solicitações de viagens; 
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e Fornecer uma API onde os motoristas interessados possam 
obter viagens; 

e Mas somente devolver para estes motoristas interessados as 
viagens que geograficamente estiverem próximas deles. 


Vamos então criar a classe TravelService , que vai 
desempenhar a função de chamar o repositório para salvar o 
pedido: 


(Component 
public class TravelService { 


@Autowired 
TravelRequestRepository travelRequestRepository; 


public TravelRequest saveTravelRequest(TravelRequest travelRe 
quest) { 
return travelRequestRepository.save(travelRequest ); 


Com isso, já podemos fazer a TravelRequestAPI ter uma 
referência para TravelService e salvar a solicitação de viagem: 


public class TravelRequestAPI { 
@Autowired 
TravelService travelService; 
@PostMapping 
public void makeTravelRequest (@RequestBody TravelRequest tra 


velRequest) { 
travelService.saveTravelRequest(travelRequest ) ; 


Com isso, só o que falta é determinar o que será retornado para 
o usuário. Diferentemente de outros recursos, este é um que deve 
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sofrer uma mudança com o passar do tempo, ou seja, uma resposta 
para o cliente pode ser dada nesse momento, mas essa é uma 
resposta apenas intermediária. No nosso caso de uso específico, a 
resposta definitiva deve vir quando algum motorista aceitar a 
viagem; mas isso costuma ser comum quando há o uso de 
mensageria e requisições assíncronas. 


Esse é um caso em que costumamos retornar o código HTTP 
202 Accepted . Esse código nos obriga a retornar um cabeçalho 
Location , que o cliente pode usar para consultar o resultado 

definitivo da requisição. Isso significa que precisamos agora ter 
uma API onde seja possível consultar o status da requisição e, 
portanto, que esta requisição precisa ter um status. No entanto, 
perceba que esse status só seria necessário na saída da API, e não 
na requisição. Em outras palavras, se eu colocar um campo 
chamado status na TravelRequest apenas com a finalidade 
de deixar isso disponível na saída da minha API, ele estaria 
acessível também na requisição, apesar de desnecessário. Como 
corrigir isso? 


A forma ideal de corrigir seria através do design pattern Data 
Transfer Object . Ele consiste na criação de objetos que servirão 
de intermediários na transmissão de dados, o que é exatamente o 
que precisamos. Assim sendo, vamos criar as classes que vão fazer 
a representação da entrada de dados da nossa API e também da 
saída. Vamos nomear a classe de entrada de 

TravelRequestInput : 


package app.car.cap03. interfaces. input; 


import app.car.cap03.domain.Passenger; 
import lombok.Data; 
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@Data 
public class TravelRequestInput { 


Passenger passenger; 
String origin; 
String destination; 


Observe que nessa classe temos também uma referéncia ao 
objeto Passenger , sendo que na verdade precisariamos apenas 
do id dele. Fazendo a substituição, temos a classe: 


public class TravelRequestInput { 


Long passengerId; 
String origin; 
String destination; 


Agora, podemos fazer a substituição na nossa API: 


@PostMapping 
public void makeTravelRequest (@RequestBody TravelRequestInput tr 
avelRequest) { 

travelService.saveTravelRequest(travelRequest ) ; 


} 


Agora, temos um outro problema: a travelRequestInput 

não é compatível com o travelService . Não podemos fazer a 
travelService passar a aceitar a TravelRequestInput pois 
isso feriria os princípios da arquitetura limpa. Ou seja, precisamos 
fazer o mapeamento das entidades nesta mesma camada. Para isso, 
vamos criar uma classe chamada TravelRequestMapper . Esta 
classe vai definir um método que faça o mapeamento do 
TravelRequestInput para um objeto do tipo TravelRequest , 
inclusive procurando pelo passageiro (e lançando um código 404 
caso não encontre): 


package app.car.cap03.interfaces.mapping; 
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//imports omitidos 


@Component 
public class TravelRequestMapper { 


@Autowired 
private PassengerRepository passengerRepository; 


public TravelRequest map(TravelRequestInput input) { 


Passenger passenger = passengerRepository.findById(input.ge 
tPassengerId()) 
.orElseThrow(() -> new ResponseStatusException(HttpStatu 
s.NOT FOUND)); 


TravelRequest travelRequest = new TravelRequest(); 
travelRequest.setOrigin(input.getOrigin()); 
travelRequest .setDestination(input.getDestination()); 
travelRequest .setPassenger (passenger); 


return travelRequest; 


Vamos modificar nossa classe de API para utilizar o 
componente de mapeamento antes de repassar os dados para a 
classe de servico: 


public class TravelRequestAPI { 


@Autowired 
TravelService travelService; 


@Autowired 
TravelRequestMapper mapper; 


@PostMapping 
public void makeTravelRequest (@RequestBody TravelRequestInpu 
t travelRequestInput) { 
travelService.saveTravelRequest (mapper .map(travelRequestI 
nput)); 
} 


3.3 CRIAÇÃO DO SERVIÇO DE SOLICITAÇÃO DE VIAGENS 67 


E criar um enum que represente os possiveis status para as 
solicitações (ou seja, solicitação criada, aceita ou recusada): 


package app.car.cap03. domain; 


public enum TravelRequestStatus { 
CREATED, ACCEPTED, REFUSED; 


Vamos agora vincular esse enum a nossa classe, e aproveitar 
para criar um campo que represente a data de criação da 
solicitação: 


@Data 
@Entity 
public class TravelRequest { 


@Id 
@GeneratedValue 
Long id; 


@ManyToOne 
Passenger passenger; 
String origin; 
String destination; 


@Enumerated(EnumType. STRING) 
TravelRequestStatus status; 
Date creationDate; 


O último passo nesse quesito é modificar a TravelService 
para popular esses campos com os valores corretos antes de salvar 
no banco: 


public TravelRequest saveTravelRequest(TravelRequest travelReques 
t) { 
travelRequest.setStatus(TravelRequestStatus.CREATED); 
travelRequest.setCreationDate(new Date()); 
return travelRequestRepository.save(travelRequest ); 
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3.4 INSERINDO LINKS: PRIMEIRO USO DE 
HATEOAS 


Vamos agora criar uma classe para representar a saida da nossa 
API, da mesma forma como fizemos com a entrada. Vamos 
começar copiando os atributos da classe TravelRequest tirando 
apenas as anotações: 


public class TravelRequestOutput { 


Long id; 

Passenger passenger; 

String origin; 

String destination; 
TravelRequestStatus status; 
Date creationDate; 


Observe a presença da classe Passenger . Esta classe, por si só, 
é tratada em uma API separada. Se utilizarmos a classe 
TravelRequestOutput da forma como está, o passageiro como 
um todo será referenciado na resposta - algo que talvez não seja 
desejado. Podemos tratar este caso utilizando uma técnica 
chamada de HATEOAS. 


HATEOAS é abreviação para Hypermedia As The Engine Of 
Application State, ou Hipermídia como o motor de estado da 
aplicação . Este é um nome grande para indicar a noção de que 
REST deve utilizar links para relacionar recursos conectados entre 
si. 


Pense em uma página da web. Ao acessar uma página, diversos 
recursos são carregados de formas distintas. A página em si vem de 
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uma vez só, mas contendo diversos links para JavaScript, CSS e 
imagens relacionadas. Todos esses recursos são carregados ao final, 
mas seguir com essa estratégia tem várias vantagens, como o cache 
separado dos recursos e a possibilidade de fazer a carga de forma 
paralela ou mesmo sob demanda. 


Da mesma forma, em REST utilizamos esses conceitos para 
demonstrar a relação entre recursos que estão conectados entre si, 
mas não necessariamente pertencem um ao outro. Quando 
queremos demonstrar essa relação, utilizamos links. 


O Spring facilita a criação desses links com o subprojeto 
Spring HATEOAS . Para utilizá-lo, vamos adicionar a seguinte 
dependência no nosso pom.xml : 
<dependency> 
<groupId>org.springframework. hateoas</groupId> 


<artifactId>spring-hateoas</artifactId> 
</dependency> 


O próximo passo é alterar a classe TravelRequestOutput 
para que esta não mais tenha uma referência para Passenger . 
Vamos usar o Spring HATEOAS para construir essa referência 
fora desta classe, de forma que ela passa a ter a seguinte estrutura: 


package app.car.cap03. interfaces.output; 


import app.car.cap03.domain.TravelRequestStatus; 
import java.util.Date; 
import lombok.Data; 


@Data 
public class TravelRequestOutput { 


Long id; 

String origin; 

String destination; 
TravelRequestStatus status; 
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Date creationDate; 


Vamos agora construir um método na classe 
TravelRequestMapper que faça o mapeamento do resultado do 
processamento contido na classe TravelRequest para a classe 
TravelRequestOutput . Esse método vai fazer apenas uma 
transposição dos valores: 


public TravelRequestOutput map(TravelRequest travelRequest) { 
TravelRequestOutput travelRequestOutput = new TravelRequestOut 


put(); 


travelRequestOutput.setCreationDate(travelRequest.getCreationD 
ate()); 
travelRequestOutput.setDestination(travelRequest .getDestinatio 


n()); 
travelRequestOutput.setId(travelRequest.getId()); 


travelRequestOutput.setOrigin(travelRequest.getOrigin()); 
travelRequestOutput.setStatus(travelRequest.getStatus()); 


return travelRequestOutput; 


Agora é onde vamos começar a usar o Spring HATEOAS para 
construir nossa estrutura. O Spring HATEOAS nos fornece uma 
hierarquia de classes para lidar com recursos de varios tipos: 


e Para trabalhar com links de uma única entidade, a melhor 
classe a ser utilizada é a 
org.springframework.hateoas.EntityModel ; 

e Para trabalhar com links sobre uma coleção de entidades, a 
melhor classe a ser utilizada é a 
org. springframework.hateoas.CollectionModel ; 

e Para trabalhar com links sobre uma coleção com suporte a 
paginação, a melhor classe a ser utilizada é a 


org. springframework.hateoas.PagedModel ; 
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e Caso nenhuma das classes acima atenda as necessidades do 
projeto, é possível criar uma extensão da classe 
org. springframework.hateoas.RepresentationModel 
(que todas as classes listadas acima já estendem). 


Conforme visto, podemos assumir que a melhor classe a ser 
utilizada para retornar o link com a referência ao passageiro é a 
EntityModel . Assim, vamos criar mais um método na classe 
TravelRequestMapper que receba tanto o TravelRequest 
quando o TravelRequestOutput que foi construído pelo método 
map . Dessa forma, esse método deverá retornar um objeto do tipo 

EntityModel : 


public EntityModel<TravelRequestOutput> buildOutputModel ( 
TravelRequest travelRequest, TravelRequestOutput output) { 


EntityModel<TravelRequestOutput> model = new EntityModel<>(out 


put); 
return model; 


} 


O último ponto a ser construído é a representação do link em 
si. Para isso, no entanto, temos que entender como um link 
funciona. 


Um link HATEOAS tem a mesma forma que um link em uma 
página da web. Isso quer dizer que existem alguns atributos básicos 
que ele precisa definir (por exemplo: qual tipo de relação ele 
apresenta com o recurso atual) e alguns atributos opcionais, como 
um título explicativo do que aquele link contém. Além disso, 
obviamente ele precisa da URL para onde aquele link leva. 


O Spring HATEOAS nos fornece uma classe que dá assistência 
para criação de links, a 
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org.springframework.hateoas.server.mvc.WebMvcLinkBuild 
er . Essa classe consegue referenciar classes de APIs (como a 

PassengerAPI ), de maneira que, caso mudemos a URL da API 
referenciada, os links recebam a atualização automaticamente. Isso 
é feito através do método linkTo , passando a classe da API como 
parâmetro: 


Link passengerLink = WebMvcLinkBuilder .linkTo(PassengerAPI.class) 
; 

No entanto, esse código não compila. Ele continua 
referenciando o builder , indicando que ainda existem alguns 
dados que precisamos fornecer. O próximo dado éo rel, ou seja, 
a construção de um atributo do link que indica o que está sendo 
representado - no nosso caso, um passageiro. Vamos então utilizar 
o método withRel passando o passenger como parâmetro: 
Link passengerLink = WebMvcLinkBuilder 


. LinkTo(PassengerAPI.class); 
.withRel("passenger"); 


Da forma como está, ele já compila. Mas seria interessante 
acrescentar apenas um atributo explicativo para esse link, para que 
fique mais fácil para o cliente decidir se precisa seguir o link ou 
não. Esse atributo explicativo é chamado title, e um bom valor 
para ele seria o nome do passageiro. Vamos utilizar o método 
withTitle para fazer essa associação: 

Link passengerLink = WebMvcLinkBuilder 
. LinkTo(PassengerAPI.class) 


.withRel("passenger") 
.withTitle(travelRequest.getPassenger().getName() 


); 


Finalmente, nosso link está construído. Agora, basta adicioná- 
lo ao modelo que construímos antes. O método 
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buildOutputModel fica assim: 


public EntityModel<TravelRequestOutput> buildOutputModel(TravelRe 
quest travelRequest, TravelRequestOutput output) { 
EntityModel<TravelRequestOutput> model = new EntityModel<>(out 


put); 


Link passengerLink = WebMvcLinkBuilder 
. LinkTo(PassengerAPI.class) 
.Slash(travelRequest.getPassenger().getId()) 
-withRel("passenger") 
-withTitle(travelRequest.getPassenger().getName()); 

model.add(passengerLink) ; 

return model; 


} 
Agora, precisamos alterar a classe de API. Temos que realizar o 
seguinte: 
1. Primeiro temos que alterar o tipo de retorno (para retornar o 
EntityModel ). 
2. Depois, temos que modificar o método para construir um 
TravelRequestOutput (através do método map ). 
3. Construir um EntityModel (através do método 
buildOutputModel ). 
O código com essas alterações fica assim: 
@PostMapping 


public EntityModel<TravelRequestOutput> makeTravelRequest (@Reque 
stBody TravelRequestInput travelRequestInput) { 

TravelRequest request = travelService.saveTravelRequest (mapper 
.map(travelRequestInput)); 

TravelRequestOutput output = mapper.map(request); 

return mapper.buildOutputModel(request, output); 


Finalmente, vamos testar nossa API. Primeiro, vamos recriar o 
passageiro: 
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POST ~  http;//localhost:8080/passengers 





(9) Body @ 
none ® form-data  xwww-form-urlencoded @ raw 
o Dath a 
2 } name”: “Alexandre Saudate 
a | 
Body Coi 4 B T 
Pretty j BETA (SON + 
1 i 
2 "id"c. 1; 
3 "name": "Alexandre Saudate" 
4 ft 


Figura 3.1: Realizando a criação do passageiro 


Na sequência, vamos utilizar o id do passageiro para enviar a 


requisição de solicitação de viagem: 
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POST ~ _ http://localhost:8080/travelRequest 


Params  Authorizatio Headers (9) Body @ = Pre-rec 





& none @ form-data & xwww-form-urlencoded raw © binary 


ie 
2 “passengerId”:"1", 
3 “origin”: "Casa", 
4 j "destination™: “Trabalho” 
3 
Body es H i) Te ilt 
Pretty Ray, Previ isualizeBETA SON ~ 5 
1 f 
2 ez 
3 "origin": "Casa", 
4 "destination": "Trabalho", 
5 "status": "CREATED", 
6 "creationDate": "2019-11-12T12:12:36.913+0000", 
7 "links": { 
8 "passenger": { 
a "href": "http: //localhost:8080/passengers", 
10 "title": "Alexandre Saudate" 
11 } 
12 } 
13 k 


Figura 3.2: Realizando a criação da solicitação de viagem 


Note a presença do JSON contendo o link para o passageiro: 


{ 
wid": 2; 
"origin": "Casa", 
"destination": "Trabalho", 


"status": "CREATED", 
"creationDate": "2019-11-12T12:12:36.913+0000", 
"links": { 
"passenger": { 
"href": "http://localhost :8080/passengers", 
"title": "Alexandre Saudate" 
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No entanto, observe que o atributo href esta incompleto. 
Para referenciar o passageiro exato, o ID do passageiro deveria 
estar na URL. Por que isso aconteceu? 


Quando utilizamos o método linkTo da classe 
WebMvcLinkBuilder , passamos como parâmetro a classe 
PassengerAPI . Isso dá ao builder a capacidade de encontrar a 
API mais geral de passageiros (como de fato aconteceu), mas não a 
API específica para listar um único passageiro. Neste caso, temos 
duas alternativas: ou construir manualmente o restante da URL ou 
fornecer para o builder o método específico para listar um 
único passageiro. Vamos seguir pela construção manual. Para isso, 
vamos utilizar o método slash do builder , passando como 
parâmetro o ID do passageiro: 
Link passengerLink = WebMvcLinkBuilder 
. LinkTo(PassengerAPI.class) 
.slash(travelRequest.getPassenger().getId()) 


.withRel("passenger") 
.withTitle(travelRequest.getPassenger().getName()); 
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POST 


® none 


= — http://ocalhost:8080/travelRequest 


Headers (9) Body @ Pre-request Script 





© form-data @ x-www-form-urlencoded raw = ® binary 


“passengerId”:"1", 
“origin”:“Casa”, 
“destination”:"Trabalho” 


es Headers (3) est Resu 
Raw Preview jsuaiize BETA SON = 5 
1 
é ES A 
"origin": "Casa", 
"destination": "Trabalho", 
"status": "CREATED", 
"creationDate": “2019-11-12712:25:43.386+0000", 
"_ links": { 
"passenger": { 
"href": “http://localhost:8080/passengers/1", 
"title": "Alexandre Saudate" 
} 
i } 


Figura 3.3: Refazendo a solicitação de viagem 


Observe que o link está na forma correta agora: 


"ig" . 2 

ha + 
"origin": "Casa", 
"destination": "Trabalho", 


"status": "CREATED", 
"creationDate": "2019-11-12T12:25:43.386+0000", 
"links": { 


"passenger": { 


"href": "http://localhost :8080/passengers/1i", 
"title": "Alexandre Saudate" 
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Conclusão 


Neste capítulo, vimos um pouco sobre como recursos 
referenciam uns aos outros, até conhecermos a técnica HATEOAS. 
Ainda não vimos como um motorista vai aceitar corridas próximas 
a ele - o que vai nos levar a construir um cliente REST para a API 
do Google Maps. 
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CAPÍTULO 4 


CRIANDO CLIENTES REST 


"O sucesso depende de preparação prévia.” - Confúcio 


Até aqui, vimos o básico sobre algumas técnicas de REST no 
lado do servidor. Para isso, construímos uma API minimamente 
funcional onde as solicitações de viagens são criadas. Mas e quanto 
à API de aceite de solicitações de viagens? Como fica? 


Neste capítulo, vamos construir essa API, e veremos como 
construir um cliente para a API do Google Maps para que o 
motorista receba somente as solicitações de viagens que estiverem 
próximas a ele. 


4.1 REORGANIZANDO O PROJETO 


Em primeiro lugar, vamos acomodar as classes que vão receber 
a estrutura. Nosso projeto está seguindo a seguinte arquitetura: 
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Figura 4.1: Diagrama de arquitetura do projeto 


Procurei unificar nesta arquitetura o conceito de clean 
architecture segundo Uncle Bob (MARTIN, 2012) com alguns 
conceitos de Domain-Driven Design, conforme descrito por Eric 
Evans (EVANS, 2003). Assim sendo, note que é uma arquitetura 
que mimetiza uma cebola: as requisições entram pela camada mais 
externa (as APIs que estão no pacote interfaces. incoming ) e 
vão penetrando até chegar às interfaces de saída (que estão 
presentes no pacote interfaces.outcoming ). 


No nosso projeto, as interfaces de entrada são APIs REST, mas 
poderiam também ser listeners de mensagens JMS, por exemplo. A 
parte de dominio contém a nossa lógica de negócio, que no caso é 
representada pelas entidades e repositórios (apenas lembrando 
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que, de acordo com o DDD, repositórios fazem parte do dominio). 
Finalmente, as interfaces de saída são clientes de outras aplicações. 
No nosso caso, é onde estará localizado o cliente para o Google 
Maps. 


Assim sendo, rearranjamos os pacotes da aplicação para 
acomodar essa estrutura: 


v main 


v Es cap04 
* D domain 
€ Driver 
® DriverRepository 
‘© Passenger 
= PassengerRepository 
‘© TravelRequest 
® TravelRequestRepository 
‘© TravelRequestStatus 
‘© TravelService 
interfaces 
vy D incoming 
» Em input 
> mapping 
» & output 
‘© DriverAPI 
‘© PassengerAPI 
‘© TravelRequestAPI 
outcoming 
‘© Cap04Application 


Figura 4.2: Reorganização dos pacotes 


4.2 CRIANDO A CHAVE DE API DO GOOGLE 


Vamos conhecer a página do Google. O serviço que queremos 
é o que fornece rotas entre localizações. Tudo isso está descrito em 
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https://developers.google.com/maps/documentation/directions/sta 
rt#sample-request. 


Sample request and response 


You access the Directions API through an HTTP interface, with requests constructed as a URL string, using text strings or 
latitude/longitude coordinates to identify the locations, along with your API key. 


The following example requests the driving directions from Disneyland to Universal Studios Hollywood, in JSON format: 


oo 
https ://maps.googleapis .com/maps/api/directions/json?origin=Disneyland&destination=Universal+Studios+Hollyw 


Try it! You can test this request by entering the URL into your web browser (be sure to replace YOUR_API_KEY with your 
actual API key). The response returns the driving directions. 


View the developer's guide for more information about building request URLs and available parameters and 
understanding the response. 


Below is a sample response, in JSON: 


{ 
"geocoded_waypoints” : [ 
{ 
“geocoder_status" : "OK", 
“place id” : "ChIJRVY_etDX3IARGYLVpoq7f68", 
“types” : [ 
"bus. station”, 
“transit station”, 
“point of interest", 
“establishment” 
] 
h 
{ 
"geocoder status” : "OK", 
“partial match" : true, 
“place id” : "ChIJp2Mn4E2-woARQS2FIL1xUzk", 


Figura 4.3: Apresentação da página da API do Google Maps 


Observe que a página traz um link de exemplo: 
https://maps.googleapis.com/maps/api/directions/json? 
origin=Disneyland&destination=Universal+Studios+Hollywood& 
key=YOUR_API_KEY. Ao copiar e colar essa URL em nosso 
browser, temos a seguinte resposta: 


{ 

"error_message": "The provided API key is invalid.", 
"routes": [], 

"status": "REQUEST_DENIED" 


J 
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Isso quer dizer que a chave de API é inválida. Mas vamos 
analisar a URL fornecida: a seção 
https://maps.googleapis.com/maps/api/directions/json é 
a base da API. A partir do sinal de interrogação, temos os 
chamados query parameters , ou seja, o sistema de 
parametrização da API. Estes são pares chave-valor separados por 
& , então temos os parâmetros origin, destination e key. 
Os valores são Disneyland, Universal Studios Hollywood e 
YOUR API KEY, respectivamente. Perceba que, de fato, a chave da 
API é apenas um placeholder. 


Para conseguir uma chave de API, existe uma seção na própria 
página demonstrando isso: 


Authentication, quotas, pricing, and policies 


Activate the API and get an API key 


To use the Directions API, you must first activate the API in the Google Cloud Platform Console and obtain the proper 
authentication credentials. You need to provide an API key in each request (or a client ID if you have a Premium Plan). 


Click the button below to follow a process where you will: 
1. Create or select a project 
2. Enable the API 
3. Getan API key 


Get Started 





Learn more about authentication credentials. 


Quotas and pricing 


Review the usage and billing page for details on the quotas and pricing set for the Directions API. 


Figura 4.4: Ativação da API do Google 


As instruções dizem para criar um projeto, habilitar a API e 
então, conseguir uma chave de API. Vamos seguir o 
procedimento, clicando no botão Get Started . Ao fazer isso, 
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somos levados a uma outra pagina, perguntando quais APIs 
queremos utilizar, dando as opções do Google Maps, Routes e 
Places. Vamos marcar os dois primeiros e seguir: 


E? Ativar a Plataforma Google Maps 


Orientaremos você pelas seguintes etapas para ativar APIs ou configurar o 


faturamento 





1. Escolha os produtos abaixo. 
2 Selecione um projeto 
3. Configure seu faturamento 


Maps | Routes [O Places 
oporcione i Mosveänats N 


alização de mapas que ina etalhe 








Figura 4.5: Ativação do Google Maps 


Ao seguir, ele nos pergunta qual é o projeto. Vou criar o 
projeto RESTBook e seguir (caso você siga este passo a passo, pode 
colocar o nome que preferir, pois isso não afeta a funcionalidade): 
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Ad Enable Google Maps Platform 


To enable APIs or set up billing, we'll guide you through a few tasks: 


1. Pick product(s) below 
2. Select a project 
3. Set up your billing 


Projects allow you to use APIs, add collaborators, and manage permissions. 
Selec’ or creale puayect 

+ Create a new project 

My Project 
My Project 1 








My Project 4103 


NewAgent 





Figura 4.6: Criação do projeto 


Se você ainda não tiver uma conta do Google, isso o levará para 
a tela pedindo para ativar a cobrança: 


Ativar o faturamento do projeto "RESTBook" 


Você não é administrador de nenhuma conta de faturamento, Para ativar o 
faturamento neste projeto, crie uma nova conta de faturamento ou entre em 
contato com o administrador da conta de faturamento para que ele o ative para 
você, Saiba mais 


CANCELAR CRIAR CONTA DE FATURAMENTO 





Figura 4.7: Ativação do billing 


Não se preocupe com esta cobrança. Conforme mencionado 
pela tela seguinte, o Google oferece (até o momento) 300 dólares 
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para serem gastos nos próximos 12 meses. Ou seja, você pode usar 
livremente os recursos da plataforma até um limite de 300 dolares 
(os valores cobrados costumam girar em torno de alguns 
centavos). Conforme diz a pagina, o cartão de crédito é requerido 
para fins de validação, mas nenhuma cobrança será feita sem seu 
consentimento: 


Teste o Google Cloud Platform gratultamente 


Etapa 1 de 2 Acesso a todos os produtos do Cloud 
Platform 


Tenha tudo o que você precisa para criar e executar 
apps, sites e serviços, incluindo o Firebase e a API 





Googie Maps. 
Termos de Serviço Crédito de US$ 300 gratuito 
OD Lie concordo com os Termos de Serviço da avaliaglie gratuita do A Inscreva-se e receba USS 300 para gastar no Google 


ud Pistform " Cloud Platform nos próximos 12 meses 


gle Clos 






Nenhuma cobrança automática será 
feita após o término da avaliação 


= aratura 


Solicitamos seu cartão de crédito para ter certeza de 
que você não é um robô. Você não será cobrado, a 
menos que atualize manualmente para uma conta 





Figura 4.8: Primeira etapa da criação do billing 


Conforme for seguindo com o processo, haverá um formulário 
a ser preenchido com o endereço e o cartão de crédito. Preencha os 
dados e clique em Iniciar minha avaliação gratuita: 
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Como você fará o pagamento 
5 Pagamentos automáticos 


Você pagará por esse serviço apenas depois de acumular custos. O 
pagamento será efetuado por meio de uma cobrança automática quando 
você atingir o limite de faturamento ou 30 dias após o último pagamento 
automático, o que ocorrer primeiro. 


Forma de pagamento (7) 






às info n 
pag . E rm 
Politica de Privacidade do Google. 





INICIAR MINHA AVALIACAO GRATUITA 


Figura 4.9: Ativando billing 


Ao concluir o processo, um último pop-up vai ser aberto para 
reforçar estas informações: 
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© Google Cloud Platform 


Ola, Alexandre, 
Agradecemos por você se inscrever na avaliação gratuita de 12 meses. 
Agradecemos sua inscrição. A avaliação gratuita inclui US$ 300 em crédito para gastar 


nos próximos 12 meses. Se os créditos acabarem, não se preocupe. Você não será 
cobrado sem sua permissão. 





Figura 4.10: Confirmação de ativação do billing Google Cloud 


Depois dessas etapas, você será levado ao painel de 
gerenciamento do Google Cloud, onde haverá um pop-up 


semelhante ao seguinte: 


BY ativar o Google Maps Platform 


Ativar as APIs 


Isso ativara 10 API(s) Google Maps Platform e criará uma chave de API para a 
implementação 


CANCELAR PRÓXIMA 





Figura 4.11: Pop-up de ativação do Google Maps Platform 


Ao clicar em Próxima , uma tela semelhante à seguinte deverá 


surgir: 
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Ad Ativar o Google Maps Platform 


You're all set! 
You're ready to start developing! 
YOUR API KEY 


as [a 


É» To improve your app's security restrict this key's usage in the AP) Console 





Figura 4.12: Pop-up com a API Key 


Copie a API Key . Vamos refazer a requisição que fizemos no 
inicio do capítulo para o Google Maps, mas desta vez, vamos 
substituir o YOUR API KEY pela API Key que você acabou de 


conseguir. O resultado é um JSON contendo o descritivo do 
Google Maps, como o seguinte: 
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“geocoded waypoints": [ 
{ 

"geocoder_ status": “OK”, 

"place id": "ChIJ96XKNOZ-3YgRoPEC@BS85Hqc", 

"types": [ 
“amusement_park", 
"establishment", 
“point of interest", 
“tourist attraction”, 
“travel agency" 


“geocoder status": “OK”, 
"place id": "ChIJzzgyJU--woARcZqceSdQ3dM", 
“types”: [ 

“amusement park”, 

"establishment", 

“point_of interest", 

“tourist attraction" 


$ 
l: 
“routes™: [ 
{ 
“pounds”: { 
"northeast": { 
"lat": 34.1358593, 
"Ing": -81.5573272 
} 
“southwest”: { 
"lat": 28.3780416, 
"Lng": -118.3511633 


} 
x 
“copyrights”: “Dados cartográficos ©2019 Google, INEGI", 
"Legs": [ 
{ 
"distance": { 
"text": "2.520 mi", 
“value": 4656271 
+ 
“duration”: { 
"text": "I dia 12 horas”, 
“value”: 129186 
}, 
“end address": “106 Universal City Plaza, Universal City, CA 91668, EUA”, 
“end location": { 
Co "Lat": 34.1358593, 
“Ing”: -118.3511633 
b 
“start address": “Walt Disney World Resort, Orlando, FL 32830, EUA", 
“start location": { 
“lat”: 28.3780416, 
“Ing”: -81.6037027 
k 
"steps": [ 
{ 


Figura 4.13: Resposta do Google Maps 
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4.3 CRIANDO O CODIGO DO CLIENTE 


Agora que já temos a comunicação com o serviço do Google 
Maps estabelecida, vamos criar a classe para realizar a busca do 
tempo de distância automaticamente. Primeiramente, vamos criar 
uma classe com um método getDistanceBetweenAddresses , 
cujo retorno seja um Integer: 


package app.car.cap04.interfaces.outcoming; 
import org.springframework.stereotype.Service; 


@Service 
public class GMapsService { 


public Integer getDistanceBetweenAddresses(String addressOne, 
String addressTwo) { 
return 0; 


} 


O próximo passo é extrair o endereço que vimos anteriormente 
para um template. Isto significa que vamos retirar os valores da 
query string e substituir por pares de template (que são delimitados 
por chaves {} ). Vamos então colocar esse endereço em uma 
constante: 
private static final String GMAPS TEMPLATE = 

"https://maps.googleapis.com/maps/api/directions/json?origin={ 
origin}&destination={destination}&key={key}"; 

Feito isso, vamos utilizar um recurso do Spring que é injetar 
alguns valores - no nosso caso, é interessante retirar a API KEY 
do projeto e colocar em um arquivo chamado 

application.properties , que fica dentro da pasta do nosso 


projeto src/main/resources : 
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= Utiivel 
® DriverRepository 
‘© Passenger 
® PassengerRepository 
‘© TravelRequest 
® TravelRequestRepository 
© TravelRequestStatus 
‘© TravelService 
+ D interfaces 
» B incoming 
y © outcoming 
“E GMapsService 
‘© capo4Application 
+ F resources 
Em static 
E» templates 
@ application.properties 
> im test 
» Bs target 
= HELP.md 
= mvnw 


Figura 4.14: Localização do arquivo application.properties 
Dentro desse arquivo vamos colocar uma propriedade com a 


API KEY do Google Maps: 


app.car.domain.googlemaps.apikey=SUA API KEY 
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ONDE COLOCAR A API KEY? 


Em uma aplicação do mundo real, é preferível que essa chave 
não fique no arquivo de propriedades, pois pode ser vazada 
por desenvolvedores mal-intencionados. Hoje em dia, 
contamos com guias como as aplicações de 12 fatores 
(WIGGINS, 2017) para nos orientar a respeito de como lidar 
com essas propriedades. O terceiro fator trata sobre 
configurações desse tipo, sendo que o preferível é armazená- 
las em variáveis de ambiente. Desta forma, apenas as pessoas 
responsáveis por realizar a manutenção da aplicação em 
produção poderiam ter acesso ao valor real da chave, 
limitando o acesso a ela. 


Além de variáveis de ambiente, existem outras variantes caso 


você use um cloud provider como a AWS. A AWS conta com 


um serviço específico chamado AWS Systems Manager 
(SSM), que trata de maneira especializada o acesso a 
parâmetros sensíveis como esse. Usando o SSM, é possível 
garantir que apenas a aplicação e a pessoa que gerou a API 
Key tenham acesso a ela. 





De volta à classe GMapsService , vamos criar um atributo 
para receber esse valor, através do uso da anotação (Value do 
Spring. Esta anotação recebe como parâmetro uma expressão que 
vai extrair o valor da propriedade e injetar nesse atributo: 


package app.car.cap04. interfaces.outcoming; 


import org.springframework.beans.factory.annotation.Value; 


94 4.3 CRIANDO O CÓDIGO DO CLIENTE 


import org.springframework.stereotype.Service; 


@Service 
public class GMapsService { 


@Value("${app.car.domain.googlemaps.apikey}") 
private String appKey; 


private static final String GMAPS_TEMPLATE = "https://maps.goo 
gleapis.com/maps/api/directions/json?origin={origin}&destination= 
{destination}&key={key}"; 


public Integer getDistanceBetweenAddresses(String addressOne, 
String addressTwo) { 
return 0; 


Agora, vamos passar à codificação do cliente, efetivamente. 
Vamos usar como apoio uma classe do Spring chamada 
RestTemplate . Essa classe fornece métodos para consumirmos 
serviços REST de diversas formas, e vai nos ajudar a consumir o 
serviço do Google. Antes, no entanto, precisamos analisar o 
serviço e de que forma precisamos do resultado dele. 


Uma análise da árvore de dados nos mostra que a informação 
de que precisamos está no elemento legs , onde existe uma 
porção chamada duration com um campo value (no nosso 
exemplo, esse dado tem o valor de 129180 ). Temos várias opções 
para extrair essa informação: poderíamos criar a estrutura de 
objetos em Java que representariam a árvore inteira. Porém, isso 
nos consumiria algum tempo para realizar o mapeamento e seria 
propenso a não se manter estável no caso de haver mudanças na 
API do Google. 


Nossa segunda opção seria realizar a extração para formato de 
mapas em Java. Apesar de essa estrutura ser um pouco mais 
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flexivel, ainda seria trabalhosa para realizar a busca do dado 
especifico (pois o Java mapearia para mapas onde os valores seriam 
outros mapas, ou seja, haveria uma complexidade para busca do 
valor). Além disso, também seria propensa a erros, pois caso 
houvesse qualquer mudança nas estruturas que fazem o acesso ao 
nosso dado específico, não seríamos mais capazes de localizar a 
informação que precisamos. 


Nossa terceira opção seria utilizar uma linguagem de busca 
específica, chamada JSONPath . Esta linguagem foi criada com o 
propósito específico de localizar informações dentro de árvores 
JSON, e uma de suas capacidades é justamente localizar dados com 
o fornecimento de apenas parte das informações necessárias. 


Seguindo com o desenvolvimento do nosso serviço, então, 
primeiramente vamos instanciar o nosso RestTemplate . Existem 
seis opções de consulta utilizando o método GET , que se 
subdividem em dois tipos principais, getForEntity e 

getForObject . Essas opções são dadas para que o usuário decida 

se quer que o método retorne um ResponseEntity ou o 
resultado diretamente. A abstração fornecida por essa classe nos dá 
a habilidade de recuperar os cabeçalhos, códigos de status etc., da 
requisição. Se esses dados não nos interessam (o que é o caso no 
momento), então podemos utilizar getForObject diretamente. 


O método getForobject é sobrecarregado por conta das 
formas de se passar os valores dos placeholders na URL. Note que, 
como a URL do Google Maps está em formato de template, temos 
que fornecer os dados de alguma forma. Pois o método é 
sobrecarregado para que passemos esses dados em formato de 

varargs , em formato de mapa, ou simplesmente não passemos 
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nada. Vamos utilizar o formato de varargs e fornecer os dados 
na sequência em que aparecem no template, isto é, o endereço de 
origem, de destino e a chave: 

RestTemplate template = new RestTemplate(); 


String jsonResult = template.getFor0Object (GMAPS TEMPLATE, String. 
class, addressOne, addressTwo, appKey); 


44 RECUPERANDO OS DADOS COM 
JSONPATH 


O próximo passo é utilizar o JSONPath para realizar essa 
busca. Antes, no entanto, precisamos adicionar a dependência de 
uma biblioteca capaz de fornecer esta capacidade: 
<dependency> 

<groupId>com. jayway.jsonpath</groupId> 


<artifactId>json-path</artifactId> 
</dependency> 


A linguagem JSONPath funciona da seguinte forma: 
primeiramente, as buscas começam com um $ . Depois, 
colocamos um . e o nome do elemento que queremos consultar. 
Caso queiramos vários elementos, vamos separando cada um com 

. .O site https://jsonpath.com/ ilustra isso: 
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JSONPath Online Evaluator - jsonpath.com 


Inputs 


Output paths 


JSONPath Syntax 
$.phoneNumbers[:1].type 


Example '$.phoneNumbers[*].type’ See also JSONPath expressions 


JSON 





Figura 4.15: Exemplo do JSONPath.com de entrada 


Evaluation Results 





Figura 4.16: Exemplo do JSONPath.com de saída 


Observe que podemos usar esse site para elaborar o resultado 
que queremos. Copie o conteúdo do JSON do Google Maps para o 
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campo Inputs do site para que possamos começar as nossas 
verificações. 


Segundo o que observamos, note que o elemento routes está 

à frente do elemento legs . Não nos interessa a declaração do 

elemento - portanto, podemos utilizar o JSONPath para localizar 

elementos em qualquer lugar da árvore, utilizando .. em vez de 
. (ficando em $..legs até o momento): 


Inputs Evaluation Results A 


Onpa pams 


IONS Syrtas 


non 





Figura 4.17: $..legs 


Agora, precisamos recuperar o elemento duration . No 
entanto, se colocarmos o JSONPath como $..legs.duration , 
nenhum resultado é retornado. O jsonpath.com dá a mensagem 
No match . Por que isso acontece? 


Acontece que o nosso elemento legs é um array. Isso 
significa que o site não conseguiu localizar o elemento duration 
pois não sabia quais elementos do array buscar (ainda que haja 
apenas um). Para fazer com que um elemento específico seja 
analisado, basta colocar entre colchetes o número desse elemento 
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(iniciando em 0). Caso queiramos que todos sejam analisados, 
então utilizamos um * . Assim, nossa query fica 
$..legs[*].duration até o momento. 


Finalmente, precisamos do campo value . Basta adicionar 
value no final da query e temos o resultado desejado: 


Inputs 


_/ Output paths 


JSONPath Syntax 
S. legs[*].duration.value 
Example '$.phoneNumbersj*].type’ See also JSONPath expressions 


Figura 4.18: A query de antes, agora completa 


Evaluation Results 


Figura 4.19: O resultado da query 


Observe que o resultado que tivemos foi um array, em vez do 
valor direto. Por que isso acontece? 


Veja que, conforme usamos .. na nossa query, podemos ter 
um resultado de tamanho indeterminado de acordo com nosso 
JSON. Assim sendo, o JSONPath retorna este array sempre que 
usamos esse elemento. Se tivéssemos usado apenas uma query 
simples, com . , ele traria o resultado simples. 


Vamos voltar ao nosso código. Como ja adicionamos a 
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biblioteca de JSONPath no nosso projeto, vamos usar o método 
parse da classe JsonPath para analisar a String que ja 
tínhamos com o JSON que precisamos: 


package app.car.cap04. interfaces.outcoming; 


import com.jayway.jsonpath. JsonPath; 

import org.springframework.beans.factory.annotation.Value; 
import org.springframework.stereotype.Service; 

import org.springframework.web.client.RestTemplate; 


@Service 
public class GMapsService { 


@Value("${app.car.domain.googlemaps.apikey}") 
private String appKey; 


private static final String GMAPS_TEMPLATE = "https://maps.goo 
gleapis.com/maps/api/directions/json?origin={origin}&destination= 
{destination}&key={key}"; 


public Integer getDistanceBetweenAddresses(String addressOne, 
String addressTwo) { 


RestTemplate template = new RestTemplate(); 
String jsonResult = template.getForObject(GMAPS_ TEMPLATE, S 
tring.class, addressOne, addressTwo, appKey); 


JsonPath.parse(jsonResult); 


return 0; 


} 


Agora, podemos invocar diretamente o método read , 
passando o JSONPath que elaboramos e atribuindo os dados a um 
JSONArray : 


JSONArray rawResults = JsonPath.parse(jsonResult).read("$..legs[* 
].duration.value"); 
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Vamos utilizar a API do Java 8 para converter os dados 
contidos no JSONArray em uma lista de Integers . Depois, 
vamos utilizar a API para recuperar o valor mínimo e, caso não 
haja valor nenhum, retornar o valor máximo possível para um 
inteiro. Isso é feito para a possibilidade de a API ter retornado 
vários valores possíveis (ou seja, várias rotas), ou nenhuma rota - 
neste caso, vamos trazer o maior número para demonstrar a 
impossibilidade de se navegar de um ponto ao outro: 


List<Integer> results = rawResults.stream().map(it -> ((Integer) 
it)).collect(Collectors.toList()); 


return results.stream().min(Integer::compareTo).orElse(Integer.MA 
X VALUE) ; 


A classe, no formato final, fica assim: 


package app.car.cap04. interfaces.outcoming; 


import com.jayway.jsonpath. JsonPath; 

import java.util.List; 

import java.util.stream.Collectors; 

import net.minidev.json.JSONArray; 

import org.springframework.beans.factory.annotation.Value; 
import org.springframework.stereotype.Service; 

import org.springframework.web.client.RestTemplate; 


@Service 
public class GMapsService { 


@Value("${app.car.domain.googlemaps.apikey}") 
private String appKey; 


private static final String GMAPS_TEMPLATE = 
"https://maps.googleapis.com/maps/api/directions/json?origi 


n={origin}&destination={destination}&key={key}"; 


public Integer getDistanceBetweenAddresses(String addressOne, 
String addressTwo) { 


102 4.4 RECUPERANDO OS DADOS COM JSONPATH 


RestTemplate template = new RestTemplate(); 
String jsonResult = template.getForObject(GMAPS_TEMPLATE, S 
tring.class, addressOne, addressTwo, appKey); 


JSONArray rawResults = JsonPath.parse(jsonResult).read("$.. 
legs[*].duration.value"); 


List<Integer> results = rawResults.stream().map(it -> ((Int 
eger) it)).collect(Collectors.toList()); 


return results.stream().min(Integer::compareTo).orElse(Inte 
ger.MAX VALUE); 


} 
} 


4.5 INTEGRANDO A CONSULTA NO PROJETO 


Vamos agora criar a API de consulta às viagens que estão 
próximas. Para isso, vamos criar um método novo na nossa classe 
de API, que vai se chamar listNearbyRequests . Esse método 
vai retornar uma lista de EntityModel<TravelRequestOutput> , 
ou seja, uma lista de retornos semelhantes ao que fizemos no 
método makeTravelRequest . Esse método também vai receber 
como parâmetro o endereço atual do motorista que utilizar essa 
API, para que possamos fazer a comparação de distância e filtrar as 
viagens que estão muito distantes do ponto atual. 


Essa API também vai ser mapeada utilizando o método GET 

(já que estamos listando dados que vêm do servidor). Como as 
requisições de viagens que vamos listar por essa API encaixam-se 
no subconjunto das solicitações de viagens que estão próximas, 
vamos criar um mapeamento para que a URL fique 
/travelRequests/nearby . Além disso, também vamos incluir 
um query parameter chamado currentAddress , para que o 
usuário da API possa receber apenas as solicitações das viagens que 
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estejam próximas desse endereço. Isso é feito através da anotação 
@RequestParan : 

@GetMapping("/nearby") 

public List<EntityModel<TravelRequestOutput>> listNearbyRequests( 


@RequestParam String currentAddress) { 
return null; 


Vamos incluir no nosso repositório um método que localize 
apenas TravelRequests que estejam no status CREATED . Para 
deixar mais genérico, um método que localize pelo status , ou 
seja, findByStatus : 
public interface TravelRequestRepository extends JpaRepository<Tr 


avelRequest, Long> { 
List<TravelRequest> findByStatus(TravelRequestStatus status); 


Como O MAPEAMENTO DOS MÉTODOS É FEITO PELO SPRING DATA? 


Como você pode observar, só o que precisamos fazer para 


criar o mapeamento do método para o banco de dados foi 


chamar o método de findByStatus . Isso faz com que o 
método siga uma convenção do próprio Spring Data e, 
portanto, o framework já faça o mapeamento automático para 
uma query de banco de dados. Caso não queiramos utilizar 
essa convenção, basta utilizar a anotação @Query . 





Vamos concentrar a nossa lógica de mapeamento na classe 
TravelService . O nosso primeiro passo nessa classe é criar uma 
constante para determinar quanto tempo será o nosso corte para 
filtragem. Observe que o campo presente na API do Google 
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retorna os dados em segundos; portanto, se quisermos que nosso 
corte seja de até 10 minutos para chegada do motorista ao ponto 
de embarque do passageiro, vamos utilizar uma constante com o 
valor 600: 


private static final int MAX_TRAVEL_TIME = 600; 


Agora, vamos injetar o serviço do Google nessa classe: 


@Autowired 
GMapsService gMapsService; 


Finalmente, vamos criar um método cujo propósito seja o de 
recuperar do banco de dados as solicitações de viagem cujos 
status sejam CREATED e, então, utilizar o serviço do Google 
para calcular o tempo de chegada em cada uma das solicitações, 
desprezando aquelas onde o tempo de chegada seja maior do que 
os 10 minutos. 


Vamos começar pela assinatura do método e recuperação dos 
dados do banco de dados: 


public List<TravelRequest> listNearbyTravelRequests(String curren 
tAddress) { 

List<TravelRequest> requests = travelRequestRepository.findByS 
tatus(TravelRequestStatus.CREATED) ; 


} 


O próximo passo é realizar a filtragem de dados utilizando o 
GMapsService . Vamos repassar o parâmetro currentaddress 
para o método  getDistanceBetweenAddresses da classe 

GMapsService , bem como o campo origin de cada 
TravelRequest , então separamos apenas as solicitações onde o 
resultado da invocação desse método for menor do que o valor 
presente na constante MAX TRAVEL TIME : 
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public List<TravelRequest> listNearbyTravelRequests(String curren 
tAddress) { 
List<TravelRequest> requests = travelRequestRepository.findByS 
tatus(TravelRequestStatus.CREATED); 
return requests 
.stream() 
.filter(tr -> gMapsService.getDistanceBetweenAddresses(curr 
entAddress, tr.getOrigin()) < MAX_TRAVEL_TIME) 
.collect(Collectors.toList()); 


} 


Voltando à nossa classe TravelRequestAPI , vamos realizar a 
chamada para o método listNearbyTravelRequests que foi 
recém-criado, para que possamos trabalhar com o resultado desse 
serviço: 

@GetMapping("/nearby") 
public List<EntityModel<TravelRequestOutput>> listNearbyRequests( 
@RequestParam String currentAddress) { 


List<TravelRequest> requests = travelService.listNearbyTravelR 
equests(currentAddress) ; 


} 

Vamos relembrar que o método buildOutputModel , que faz 
a construção da classe com o EntityModel , recebe como 
parametros um TravelRequest eum TravelRequestOutput . 
Este ultimo é construido a partir da chamada do método map , 
portanto precisamos chamar esse método primeiro e, na 
sequência, chamar o método buildoutputModel com ambos. 
Para simplificar essas chamadas, vamos criar um novo método na 
classe TravelRequestMapper que vai receber a lista de 
TravelRequest e vai chamar, para cada uma, o método map e 
depois o buildoutputModel - desta forma, retornando uma lista 
de EntityModel<TravelRequestOutput> . Vamos chamar esse 
método de buildoutputModel (ou seja, estamos 
sobrecarregando o método que já existia): 
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public List<EntityModel<TravelRequestOutput>> 
buildOutputModel(List<TravelRequest> requests) { 
return requests 
.stream() 
.map(tr -> buildOutputModel(tr, map(tr))) 
.collect(Collectors.toList()); 


Voltando à nossa classe TravelRequestAPI , vamos fazer com 
que ela retorne o resultado da chamada ao método recém-criado: 


@GetMapping("/nearby") 
public List<EntityModel<TravelRequestOutput>> listNearbyRequests( 
@RequestParam String currentAddress) { 

List<TravelRequest> requests = travelService.listNearbyTravelR 
equests(currentAddress) ; 

return mapper .buildOutputModel(requests); 


} 


4.6 TESTANDO A NOVA API 


O ultimo passo é fazer o teste da nova API. Para isso, vamos 
recriar o passageiro: 


4.6 TESTANDO A NOVA API 107 


+ Salvar passageiro 


POST > _ http://localhost:8080/passengers 


tior Jeaders (9) Body e Pre 





& none @form-data © x-www-form-uriencoded raw ® bin 


iv { 
2 “name”: “Alexandre Saudate” 
3 y 
Body H (3) 
Pretty f isualize BTA SON >» 3 
1 ff 
2 "SOM: Ei 
3 "name": "Alexandre Saudate" 
4 q 


Figura 4.20: Passageiro recriado 


Depois, vamos criar a solicitação de viagem: 
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> Criar solicitação de viagem 


POST v — http://localhost:8080/travelRequests 


thorization leaders (9) Body @ Pre-request Script 





& none @form-data © xwww-form-urlencoded raw @hbinary & 


1 
2 “passengerid":"1”, 

3 “origin”: “Avenida Paulista, 1000", 

4 "destination": "Avenida Ipiranga, 100” 
J 


Body i Headers (3) Test Result 
Pretty Raw Preview visualize BETA JSON ¥ > 
1 ff 
2 "$d" ='Z, 
3 "origin": “Avenida Paulista, 1000", 
4 "destination": "Avenida Ipiranga, 100", 
5 "status": "CREATED", 
6 "creationDate": "2019-11-17T02:18:47.122+0000", 
7 "links": { 
8 "passenger": { 
E "href": “http://localhost:8080/passengers/1", 
10 "title": “Alexandre Saudate" 
ll } 
12 } 
3 q 


Figura 4.21: Solicitação de viagem criada 


Finalmente, vamos realizar a listagem de corridas próximas: 
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GET + — http://localhost:8080/travelRequests/nearby?currentAddress=Alameda Santos, 800 


Params @ Authorization Headers (7) Body Pre-request Script Tests Settings 





Query Params 
KEY VALUE 


currentAddress Alameda Santos, 800 


Body Cookies Headers (3) Test Results 


Pretty Raw Preview Visualize JSON ¥ > 
1 f 
2 { 
3 “gro 2, 
4 "origin": "Avenida Paulista, 100", 
5 "destination": "Avenida Faria Lima, 1300", 
6 “status”: "CREATED", 
7 "creationDate": "2020-03-28722:45:14.057+0000", 
8 “Links”: [ 
9 
10 "rel": "passenger", 
11 "href": “http: //localhost:8080/passengers/1", 
12 "title": "string" 
13 } 
14 ] 
15 } 
16 | 


Figura 4.22: Retorno da viagem que está próxima 


Observe que, caso um endereço mais distante seja passado 
como parâmetro, a corrida não é retornada: 
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GET X http;//localhost:8080/travelRequests/nearby?currentAddress=Avenida Nove de Julho, 3000 


Params @ Authorization Headers (7) 


Query Params 
KEY 


currentAddress 


Body Cookies Headers (3) Test Results 
—— 
Pretty Raw Preview Visualize 
1 @ 


ul 


Pre-request Script Tests Settings 


VALUE 


Avenida Nove de julho, 3000 


Figura 4.23: Ausência de resultados com endereço distante 


Conclusão 


Neste capítulo, conhecemos um pouco sobre como funciona a 
parte de criação de clientes REST utilizando o RestTemplate do 


Spring Boot. É claro, ainda foi um tipo de cliente superficial, que 


consome um serviço externo, mas nos dá insumos para que 


conheçamos melhor um aspecto muito importante da criação de 


serviços REST, que é a criação de testes automatizados para os 


nossos serviços. 
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CapituLo 5 


CRIANDO OS TESTES 
AUTOMATIZADOS 


"No meio do caos há sempre uma oportunidade.” - Sun Tzu 


Nossa API já oferece, efetivamente, uma funcionalidade: é 
possível que um motorista liste quais solicitações de viagens foram 
feitas próximas a ele. Ainda não criamos a API que associa a este 
motorista uma determinada viagem, mas com uma funcionalidade 
já criada, é muito importante que comecemos a criar testes 
automatizados para ela, pois são eles que vão garantir a 
estabilidade quando fizermos quaisquer mudanças. 


5.1 CONHECENDO AS ESTRATÉGIAS DE 
TESTE 


Como desenvolvedor, talvez você já esteja familiarizado com 
algumas técnicas de testes dentro do próprio ambiente, como 
testes unitários e de integração, por exemplo. Os testes unitários 
restringem-se a um único componente, e suas dependências são 
fornecidas como mocks, ou seja, retornam respostas pré- 
programadas. Já os testes de integração abrangem escopos mais 
amplos, atingindo vários componentes, algumas vezes também 
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requerendo mocks, mas procurando depender o minimo possivel 
destes. 


Quando partimos para testes de APIs, elevamos estes testes a 
um novo patamar com os testes de contrato. Os testes de contrato 
são como os testes de integração, mas são feitos testando inclusive 
a interface da API. Isso quer dizer que, se um teste de integração 
pode ser feito instanciando a classe Java que fornece a API e 
realizando uma chamada para o método, um teste de contrato vai 
requerer start no servidor e realizar uma chamada HTTP a ele. Isso 
garante que não apenas o funcionamento do sistema está dentro 
do correto, como que o sistema está realizando o mapeamento 
correto dos formatos de entrada e saída - daí o nome contrato. 


O Spring Boot, por si só, não realiza esse tipo de teste. Daí 
podemos contar com um novo framework, o REST Assured 
(disponível em http://rest-assured.io/). Ele atua em conjunto com 
o Spring Boot para fornecer testes das APIs muito poderosos. 
Vamos criar os testes da API de passageiros primeiro para verificar 
como isso funciona. 


5.2 CRIANDO OS TESTES DA API DE 
PASSAGEIROS COM REST ASSURED 


Em primeiro lugar, precisamos adicionar a dependência do 
REST Assured no nosso pom.xml . Vamos utilizar também um 
framework chamado JUnit (que é o padrão de fato para testes em 
Java), mas ele já foi incluído no projeto pelo Spring Initializr, no 
ato da criação do projeto. 


A versão mais atual do REST Assured (quando da escrita deste 
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livro) é a 4.1.2. Vamos incluir então o trecho correspondente no 

pom.xml , com o escopo de testes: 

<dependency> 
<groupId>io. rest -assured</groupId> 
<artifactId>spring-mock-mvc</artifactId> 
<version>4.1.2</version> 


<scope>test</scope> 
</dependency> 


Agora, vamos criar a classe de testes, no diretório padrão de 
testes do Maven, que é src/test/java . Vamos criar o pacote 
app.car.cap05. interfaces. incoming neste diretório, que é o 
mesmo pacote da classe PassengerAPI , que fornece a nossa API 
de passageiros. Nossa classe se chamará PassengerAPITestIT , 
ou seja, o nome da classe a ser testada acrescido do sufixo 
Test IT , que é o padrão do Maven para testes de integração. Seu 
código começa assim: 


package app.car.cap05. interfaces. incoming; 


public class PassengerAPITestIT { 
} 


Quando os testes forem executados por esta classe, a tarefa dela 
é inicializar todo o contexto do Spring, assim como o web server 
associado. Isso pode ser feito através de uma única anotação, a 
@SpringBootTest : 
import org.springframework.boot.test.context.SpringBootTest; 
@SpringBootTest 
public class PassengerAPITestIT { 


J 


Uma vez tendo isso em mente, vamos considerar que os testes 
são executados em um ambiente CI/CD (Continuous 
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Integration/Continuous Delivery). Isso significa que pode haver 
varios testes deste sistema sendo executados em paralelo - como 
proceder para que uns nao bloqueiem os outros por ocupar a 
mesma porta de rede, quando o servidor for inicializado? Lembre- 
se de que, por padrão, o sistema sempre é executado sob a porta 
8080. 


A resposta para este problema é atribuir uma porta aleatória 
toda vez que o sistema for inicializado. Isso quer dizer que o Spring 
Boot é capaz de procurar por uma porta vazia no ambiente e 
associar o web server a ela. Isso pode ser feito utilizando o 
parâmetro webEnvironment da anotação @SpringBootTest , 
passando como parâmetro a constante RANDOM PORT , da forma 
como segue: 


import org.springframework.boot.test.context.SpringBootTest; 


@SpringBootTest(webEnvironment = SpringBootTest.wWebEnvironment.RA 
NDOM PORT) 

public class PassengerAPITestIT { 

} 


Para que o REST Assured saiba qual porta utilizar para realizar 
as requisições, utilizamos um artifício do Spring Boot, que é a 
anotação @LocalServerPort . Esta anotação realiza a injeção da 
porta em um campo da classe de testes, assim: 


import org.springframework.boot.test.context.SpringBootTest; 
import org.springframework.boot.web.server.LocalServerPort; 


@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment.RA 
NDOM PORT) 
public class PassengerAPITestIT { 


@LocalServerPort 
private int port; 
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Para configurar o REST Assured com esta porta, simplesmente 
realizamos a atribuição deste valor injetado no campo port da 
classe RestAssured , de forma estática. Vamos criar um método 
onde vamos incluir esta informação, e anotá-lo com a anotação 

@BeforeEach do JUnit, que fará com que este método sempre 
seja invocado antes da execução de cada teste: 


import io.restassured.RestAssured; 

import org.junit.jupiter.api.BeforeEach; 

import org.springframework.boot.test.context.SpringBootTest; 
import org.springframework.boot.web.server.LocalServerPort; 


@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment.RA 
NDOM PORT) 
public class PassengerAPITestIT { 


@LocalServerPort 
private int port; 


@BeforeEach 
public void setup() { 
RestAssured.port = port; 


Vamos agora começar a criação do nosso teste. Para isso, 
vamos criar um método com um nome apropriado para dizer o 
que, exatamente, estamos testando. Depois, vamos anotá-lo com a 
anotação @Test do JUnit: 


package app.car.cap05. interfaces. incoming; 


import io.restassured.RestAssured; 

import org.junit.jupiter.api.BeforeEach; 

import org.junit.jupiter.api.Test; 

import org.springframework.boot.test.context.SpringBootTest; 
import org.springframework.boot.web.server.LocalServerPort; 
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@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment.RA 
NDOM_PORT ) 
public class PassengerAPITestIT { 


@LocalServerPort 
private int port; 


@BeforeEach 
public void setup() { 
RestAssured.port = port; 


} 


@Test 
public void testCreatePassenger() { 


} 


Vamos agora criar uma String contendo o JSON que usamos 
para criação de um passageiro. Não se esqueça de que as aspas 
duplas ( " ) são reservadas em Java, e portanto precisamos escapá- 


la com \: 
@Test 
public void testCreatePassenger() { 
String createPassengerJSON = "{\"name\":\"Alexandre Saudate\"} 
r 
} 


Passemos à criação do teste da API. Vamos, primeiro, reunir as 
informações acerca do básico de uma API: 


Tipo de conteúdo: JJON 

URL: /passengers 

Método HTTP: POST 

Código de retorno esperado: 200 


Com essas informações, podemos criar o teste utilizando a API 
do REST Assured. É importante observar que esta segue o conceito 
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de uma API Fluente (como apresentado por FOWLER, 2005), e é 
interessante, nesse caso, realizar importação estática do primeiro 
método, given . Esse método vai inicializar a declaração de uma 
API com o REST Assured: 


package app.car.cap05. interfaces. incoming; 
import static io.restassured.RestAssured.given; 
// restante do código omitido 


@Test 
public void testCreatePassenger() { 


String createPassengerJSON = "{\"name\":\"Alexandre Saudate\"}"; 


given(); 


Agora, vamos inserir a declaração do tipo de conteúdo, 
utilizando na sequência o método contentType e passando como 
parâmetro o valor JSON , presente na enumeração ContentType : 
given() 


.contentType(io.restassured.http.ContentType. JSON) 


Depois, vamos realizar a atribuição do corpo da requisição, 
utilizando o método body : 


String createPassengerJSON = "{\"name\":\"Alexandre Saudate\"}"; 
given() 


.contentType(io.restassured.http.ContentType. JSON) 
. body(createPassenger JSON) 


Na sequência, especificamos de uma só vez o método HTTP e a 
URL. Como o método é POST , utilizamos o método post : 
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given() 
.contentType(io.restassured.http.ContentType. JSON) 
. body(createPassenger JSON) 
.post("/passengers") 


Até aqui, fornecemos ao REST Assured todo o necessário para 
a realizar a requisição. Agora vamos começar a seção de asserções 
sobre o que foi executado, e para realizar a separação entre o 
trecho da requisição e validação da resposta utilizamos o método 
then : 
given() 

.contentType(io.restassured.http.ContentType. JSON) 

. body(createPassenger JSON) 


.post("/passengers") 
.then() 


Para verificarmos o código de retorno, utilizamos o método 
statusCode : 
given() 

.contentType(io.restassured.http.ContentType. JSON) 

. body (createPassenger JSON) 

.post("/passengers") 


.then() 
.statusCode(200) 


Finalmente, vamos nos certificar de que o JSON de resposta 
contém os campos de que precisamos, ou seja, id e name . Essa 
verificação é feita pelo método body , que recebe como 
parâmetros uma String GPath (que é muito semelhante ao 

JSONPath ) e um matcher de verificação de um framework de 
apoio, o Hamcrest. Esse matcher vai ser responsável por realizar a 
verificação de que o dado resultante da recuperação feita pelo 

GPath é igual ao que necessitamos. Neste caso, vamos usar os 
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matchers equalTo e o notNullValue . Vamos realizar a 
importação estática dos matchers e, então, executar o método: 


import static org.hamcrest.Matchers.equalTo; 
import static org.hamcrest.Matchers.notNullValue; 


// Restante do código omitido... 


given() 
.contentType(io.restassured.http.ContentType. JSON) 
. body(createPassenger JSON) 
.post("/passengers") 
.then() 
. statusCode(200) 
.body( "id", notNullvalue()) 
.body( "name", equalTo("Alexandre Saudate")) 


POR QUE REALIZAMOS A VERIFICAÇÃO DO CAMPO ID COM 


NoTNULLVALUE EM VEZ DE EquaLTO ? 


Com a execução de vários testes no projeto, pode ser que nem 
sempre o valor de um ID seja igual ao que codificamos no 


teste. Assim sendo, fazemos a verificação apenas de que o 


campo está presente, em vez de compará-lo com um valor 
específico. 





5.3 EXECUTANDO O TESTE 


Quando criamos o teste com o sufixo IT , estamos adotando 
um padrão do Maven que é utilizado para testes de integração. 
Ainda que estejamos usando um teste de contrato, há uma coisa 
em comum entre eles: o tempo de execução. Quando executo o 
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teste na minha IDE, recebo como resposta algo semelhante ao 


seguinte: 
7 ~ Test Results 2s 28ms 
+ PassengerAPITestiT 2s 28 ms 
testCreatePassenger() 2528ms 


Figura 5.1: Resultado da execução do teste na IDE 


Em minha máquina, o tempo de execução foi de 2 segundos e 
28 milissegundos. Apesar de ser um tempo relativamente rápido, 
se tivermos 10 testes para o nosso sistema que levem o mesmo 
tempo, esse tempo de execução vai subir para um pouco mais de 
20 segundos - o que já começa a ser impraticável. Mike Wacker 
(WACKER, 2015), na época da escrita do artigo Just Say No To 
More End-To-End Tests, sinalizou a sugestão do Google para testes: 
70% de testes unitários, 20% de testes de integração e 10% de testes 
end-to-end. Testes de contrato não são mencionados no artigo, 
mas estes são um tipo intermediário entre os testes de integração e 
os testes end-to end. A diferença é que os testes _end-to-end não 
usam mocks em ponto algum e os de contrato, sim. 


De qualquer forma, precisamos configurar o projeto para 
realizar a execução de testes desse tipo. Do modo como o projeto 
está configurado, os testes não serão executados pelo Maven. Isso 
porque apenas o plugin de execução de testes unitários, o Surefire, 
está configurado. O plugin que executa os testes de integração é o 
Failsafe. Para acrescentá-lo ao projeto é fácil; basta acrescentar o 
plugin na seção de build do Maven. A versão do plugin é 
gerenciada automaticamente pelo Spring Boot. Teremos algo 
semelhante ao seguinte no pom.xml : 


<build> 
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<plugins> 
<plugin> 
<groupId>org.springframework.boot</groupId> 
<artifactId>spring-boot-maven-plugin</artifactId> 
</plugin> 
<plugin> 
<groupId>org.apache.maven.plugins</groupId> 
<artifactId>maven-failsafe-plugin</artifactId> 
</plugin> 
</plugins> 
</build> 
Basta executar na raiz do projeto o comando mvn verify. 
Isso vai fazer o Maven compilar todo o projeto e então executar os 
testes (tanto unitários quanto integrados), e algo semelhante ao 


seguinte deve aparecer entre os resultados da execução: 
[INFO] Tests run: 1, Failures: O, Errors: O, Skipped: O, Time ela 


psed: 10.607 s - in app.car.cap05. interfaces. incoming. PassengeraP 
ITestIT 


5.4 TESTES MAIS COMPLETOS COM 
WIREMOCK 


Nossa API de passageiros foi mais simples de testar, pois não 
envolvia serviços externos. Já o serviço de consulta de solicitações 
de viagens é um pouco mais complexo, pois faz a consulta ao 
serviço do Google para checar o tempo de viagem. Mas não 
podemos invocar o serviço a cada execução do teste, pois isso 
eventualmente pode ser cobrado. Há também casos em que não é 
possível invocar um serviço externo por haver efeitos colaterais, 
como serviços de cobrança ou serviços mais complexos como 
ERPs. Assim sendo, a melhor estratégia seria criar um mock para 
esses serviços externos - mas que fosse algo tão próximo do real 
quanto possível. Em outras palavras, o ideal seria criar um serviço 
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que fornecesse uma API muito próxima do serviço real, mas que 
fosse controlada por nós. 


Para atender a esse propósito, existe um framework chamado 
WireMock (http://wiremock.org/). Ele utiliza uma linguagem 
fluente para que possamos criar um mock server capaz de atuar 
como um dublê do serviço que vai ser consultado na outra ponta - 
no caso, o do Google Maps. 


O Spring Boot oferece uma integração nativa com o 
WireMock, que realiza o gerenciamento automático do ciclo de 
vida do mock server. Para incluí-lo no nosso projeto, temos que 
incluir a seguinte entrada no pom.xml : 
<dependency> 

<groupId>org.springframework.cloud</groupId> 

<artifactId>spring-cloud-contract-wiremock</artifactId> 

<version>2.2.0.RELEASE</version> 


<scope>test</scope> 
</dependency> 


Como nós vamos criar esse dublê, o endereço dele será 
diferente do original do Google Maps. O Spring Boot oferece uma 
estratégia para lidar com esse tipo de cenário a partir do uso de 
profiles. Criar um profile no Spring Boot significa criar um novo 
arquivo no padrão application- (nome do profile) e populá-lo 
com os dados que a aplicação vai utilizar no cenário específico. 


No nosso caso, vamos modificar o serviço GMapsService 
para que seja possível alterar o host da API. Assim sendo, vamos 
criar um atributo nesta classe que identifique esse host e já seja 
populado por padrão com o endereço do Google, ao mesmo tempo 
que possa ser sobrescrito com o valor definido por algum profile. 
Isso pode ser feito utilizando a anotação (value , declarando a 
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chave e o valor padrão, separados por : e delimitados por { e 
) . Vamos dizer ao Spring Boot que deve preencher o atributo 
com o valor da chave interfaces.outcoming.gmaps.host e, 
caso não encontre, popular com o valor padrão 
https://maps.googleapis.com . O trecho de código fica assim: 


import org.springframework.beans.factory.annotation.Value; 
// Restante do código omitido 


@Value("${interfaces.outcoming.gmaps.host:https://maps.googleapis 
.com}") 
private String gMapsHost; 


private static final String GMAPS_TEMPLATE = "/maps/api/direction 
s/json?origin={origin}&destination={destination}&key={key}"; 


public Integer getDistanceBetweenAddresses(String addressOne, Str 
ing addressTwo) { 


RestTemplate template = new RestTemplate(); 
String jsonResult = template.getForObject(gMapsHost + GMAPS_TE 
MPLATE, String.class, addressOne, addressTwo, appKey); 


// código restante omitido 


Agora, vamos realizar a criação de classe de testes 
propriamente dita. A estrutura geral desta classe será semelhante à 
PassengerAPITestIT , inclusive com a criação de uma porta 
aleatória para os testes: 
@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment.RA 


NDOM PORT) 
public class TravelRequestAPITestIT { 


@LocalServerPort 
private int port; 


@BeforeEach 
public void setup() { 
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RestAssured.port = port; 


@Test 
public void testFindNearbyTravelRequests() { 


Vamos incluir a anotação @AutoConfigureWireMock nessa 
classe, que vai fazer com que o WireMock seja criado 
automaticamente: 


import org.springframework.cloud.contract .wiremock. AutoConfigurew 
ireMock; 


// Restante dos imports omitidos 


@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment.RA 
NDOM_PORT) 

@AutoConfigurewireMock 

public class TravelRequestAPITestIT { 

Da forma como está, o WireMock será inicializado tomando 
como base a porta 8080 (o que gera um conflito com a nossa 
própria aplicação). Podemos fazer com que ele seja inicializado em 
uma porta aleatória utilizando a propriedade port da anotação 

@AutoConfigureWireMock , passando como parâmetro a 
constante DYNAMIC PORT : 


import com.github.tomakehurst.wiremock.core.WireMockConfiguration 
r 

// Restante dos imports omitidos 

@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment.RA 
NDOM PORT) 


@AutoConfigurewireMock(port = wWireMockConfiguration.DYNAMIC PORT) 
public class TravelRequestAPITestIT { 


Vamos inserir um atributo nesta classe que vai corresponder ao 


5.4 TESTES MAIS COMPLETOS COM WIREMOCK 125 


servidor do WireMock, do tipo WireMockServer . Ele sera 
injetado pela anotação @Autowired : 


// Imports e restante do código omitido 
public class TravelRequestAPITestIT { 


@Autowired 
private WireMockServer server; 


// Restante do código omitido 


Agora, precisamos configurar um profile especial de testes, para 
que quando o teste seja executado ele use o endereço do WireMock 
em vez do endereço real. Dentro do diretório 

src/test/resources , crie um arquivo chamado application- 
test.properties (dessa forma, o nome do profile será test ). 
Ele deverá ter o seguinte conteúdo: 


interfaces.outcoming.gmaps.host=http://localhost:$(wiremock.serve 
r.port} 


O QUE ACONTECE COM A CHAVE DO GOOGLE NO PROFILE DE TESTES? 


O Spring conta com uma estrutura de encadeamento de 
valores em seus profiles. Como o arquivo que ja tínhamos não 
tem um nome de profile especificado, ele assume que todos os 


valores declarados naquele arquivo são os padrões. Portanto, 


não precisamos redeclarar os atributos, já que o Spring 
entende que aqueles valores apenas não foram sobrescritos. 





Finalmente, precisamos modificar o teste para que ele use o 
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novo profile. Isso é feito através da anotação @ActiveProfiles , 
que recebe como parametro o nome do profile que estara ativo (no 
caso, test ): 


//Restante dos imports omitidos 
import org.springframework.test.context.ActiveProfiles; 


@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment.RA 
NDOM PORT) 

@AutoConfigurewireMock(port = wWireMockConfiguration.DYNAMIC PORT) 
@ActiveProfiles("test") 

public class TravelRequestAPITestIT { 


// Restante do código omitido 


5.5 CONFIGURAÇÃO DO MOCK DO GOOGLE 
MAPS 


O próximo passo é criar o dublê do Google Maps. Para isso, 
vamos capturar mais uma vez a resposta real do serviço utilizando 
nosso browser para recuperar a distância da Avenida Paulista, 900 
para a Avenida Paulista, 1000. O endereço será, portanto, 
https://maps.googleapis.com/maps/api/directions/json? 
origin=Avenida%20Paulista,%20900&destination=Avenida%20Pa 
ulista,%201000&key=APIKEY. Observe que a resposta é 
demasiado grande para colocar em uma String, entao vamos 
colocar em um arquivo e ler a partir dele. Na pasta de fontes de 
recursos de testes do Maven ( src/test/resources ), crie a pasta 

responses/gmaps e, dentro dela, o arquivo 

sample response. json . Copie para esse arquivo a resposta do 
serviço do Google Maps. 


Vamos criar agora uma classe chamada FileUtils , que vai 
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fornecer métodos utilitários para leitura de arquivos. Dentro dela, 
vamos criar um método estático chamado loadFileContents , 
que vai receber como parâmetro o nome do arquivo a ser 
carregado. Quando carregamos arquivos do projeto, em geral 
temos que lidar com complicações em relação à mudança de 
posição do arquivo dependendo do formato do projeto (se já está 
compactado em um JAR ou não, se a posição do arquivo é alterada 
após a compilação etc.). Para não termos que lidar com essas 
complicações, utilizamos a classe ClassPathResource do Spring, 
onde passamos uma String com o nome do arquivo no construtor. 
Depois de instanciado, basta invocar o método getInputStream 
para recuperar uma InputStream com os dados do arquivo: 


package app.car.cap05.infrastructure; 


import org.springframework.core.io.ClassPathResource; 
import java.io. InputStream; 


public class Fileutils { 
public static String loadFileContents(String fileName) { 
InputStream is = new ClassPathResource(fileName).getInputst 


ream(); 
return ""; 


} 


Observe que o método  getInputStream lança uma 
java.io.I0Exception . Para não termos que lidar com essa 
exceção (e se tratando do contexto de uma classe de execução de 
testes), vamos usar a anotação do lombok @SneakyThrows , que 
vai suprimir a necessidade de declaração dessa exceção: 


import lombok.SneakyThrows; 


@SneakyThrows 
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public static String loadFileContents(String fileName) { 


InputStream is = new ClassPathResource(fileName).getInputStrea 


m(); 


return ""; 


} 


O último ponto da criação desse método é a leitura da stream. 
Temos que criar um array de bytes com o tamanho do número de 
bytes disponíveis na stream (que pode ser obtido pelo método 

available ) e, depois, chamar o método read - que vai popular 

o array de bytes. Finalmente, instanciamos uma String com esse 
array, o que vai fazer com que o conteúdo do arquivo esteja 
disponível nesta String. O método fica assim, portanto: 


@SneakyThrows 
public static String loadFileContents(String fileName) { 


InputStream is = new ClassPathResource(fileName).getInputStrea 
m(); 

byte[] data = new byte[is.available()]; 

is.read(data); 

return new String(data); 


Para criar nosso dublê, precisamos separar toda a informação 
necessária de que precisamos. O serviço do Google Maps original 
vai até uma URL chamada /maps/api/directions/json para 
obter os dados, e recebe os parâmetros através das query strings 

origin , destination e key . Ao receber uma solicitação nesta 

URL, e com os parâmetros de cada query string com o valor 
correto, o servidor do WireMock deve retornar uma resposta de 
sucesso com o JSON contido no arquivo 
sample_response.json , que já populamos com a resposta real 
do serviço. 


Para realizar toda a configuração deste servidor, vamos realizar 
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a importação estática do conteúdo da _ classe 
com.github.tomakehurst .wiremock.client.WireMock e criar 
um método separado chamado setupServer . Feito isso, vamos 
chamar o método stubFor do servidor do WireMock, iniciando 
o processo de criação do servidor. Para associar a URL ao método 
GET , vamos invocar o método get passando como parâmetro o 
resultado do método urlPathEqualTOo . Este método, por sua vez, 
vai receber a URL /maps/api/directions/json como 
parâmetro: 


import static com.github.tomakehurst.wiremock.client.wWireMock.*; 
public void setupServer() { 


server.stubFor (get (urlPathEqualTo("/maps/api/directions/json") 


)); 
} 


Ainda não terminamos a configuração. Logo após o método 
get retornar, vamos usar o método withQueryParam para 
declarar quais query params desejamos receber e quais valores. 
Esse método recebe dois parâmetros; o primeiro é o nome do 
query param em si e o segundo, um matcher semelhante ao do 
Hamcrest para comparar a query string. No caso, vamos utilizar o 
matcher chamado equalTo para declarar que esperamos receber 
valores exatamente iguais aos declarados: 
server. stubFor (get (urlPathEqualTo("/maps/api/directions/json")) 


.withQueryParam("origin", equalTo("Avenida Paulista, 900")) 
.withQueryParam("destination", equalTo("Avenida Paulista, 1000 


)) 
.withQueryParam("key", equalTo("APIKEY")) //Valor real ocultad 
); 


O último passo é realizar a declaração do retorno. O 
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WireMock oferece um atalho para respostas de sucesso com JSON 
através do método okJson . Este método recebe como parametro 
uma String, que vamos carregar a partir do método 

loadFileContents com o contetido do arquivo disponivel em 

/responses/gmaps/sample_response.json . O resultado sera 
fornecido para o método willReturn , que é a declaração final do 
conteúdo que será retornado por este mock. O conjunto fica assim: 


import static app.car.cap05.infrastructure.FileUtils.loadFileCont 
ents; 


server.stubFor (get (urlPathEqualTo("/maps/api/directions/json")) 
.withQueryParam("origin", equalTo("Avenida Paulista, 900")) 
.withQueryParam( "destination", equalTo("Avenida Paulista, 1000 


)) 
.withQueryParam("key", equalTo("APIKEY")) //Valor real ocultad 


.willReturn(okJson(loadFileContents("/responses/gmaps/sample_r 
esponse.json"))) 


); 

Finalmente, vamos realizar a criação dos testes necessários para 
verificar que tudo está funcionando. Faremos isso em um novo 
método chamado testFindNearbyTravelRequests . Dentro 
desse método, criaremos três novas invocações com o REST 
Assured: uma para a criação de um novo passageiro, outra para 
criar uma nova solicitação de viagem e a última para recuperar as 
viagens próximas. Uma única modificação que faremos nos testes 
em relação aos que foram feitos na classe PassengerAPITestIT 
são os matchers do Hamcrest para verificação de igualdade. 
Observe que utilizamos um método chamado equalTo do 
WireMock para criação do servidor e, portanto, não podemos 
utilizar o mesmo matcher no Hamcrest com importação estática. 
Para contornar essa questão, onde antes usávamos o matcher 
equalTo do Hamcrest agora vamos passar a usar o is - que tem 


5.5 CONFIGURAÇÃO DO MOCK DO GOOGLE MAPS 131 


o mesmo efeito, sendo apenas um alias. 


Também vamos aproveitar o método loadFileContents 
para criar alguns arquivos com o conteúdo das requisições. Crie 
um diretório requests/passengers api e, dentro dele, um 
arquivo chamado create new passenger.json, com o seguinte 
conteúdo: 

{ 


"name": "Alexandre Saudate" 


} 


Agora, dentro do diretório requests crie um novo diretório 
chamado travel requests api e, dentro dele, um arquivo 
chamado create new request. json . Este arquivo deverá ter o 
seguinte conteúdo: 


{ 
"passengerId":"1", 
"origin":"Avenida Paulista, 1000", 
"destination": "Avenida Ipiranga, 100" 
} 


Vamos à criação dos testes. Dentro do método 
testFindNearbyTravelRequests vamos incluir uma chamada 
ao método setupServer e depois, vamos colocar uma cópia 
bastante semelhante ao método de teste da classe 
PassengerAPITestIT . Observe que vamos modificar apenas o 
matcher do Hamcrest (de equalTo a is ) ea carga do conteúdo 
da chamada será feita a partir do método loadFileContents : 


@Test 
public void testFindNearbyTravelRequests() { 


setupServer(); 


given() 
.contentType(ContentType. JSON) 
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.body(loadFileContents("/requests/passengers_api/create_new 
_passenger.json")) 

.post("/passengers") 

. then() 

. statusCode(200) 

-body("id", notNullValue()) 

.body( "name", is("Alexandre Saudate")) 


Vamos agora fazer uma chamada semelhante ao método de 
criação de solicitações de viagens. A API está disponível na URL 
/travelRequests , recebe um JSON a partir do método POST e 
retorna o código de status 200. Também podemos realizar a 
validação de dados de forma bastante semelhante ao teste anterior: 
given() 

.contentType(ContentType. JSON) 

.body(loadFileContents("/requests/travel requests api/create n 
ew request.json")) 

.post("/travelRequests") 

.then() 

. statusCode(200) 

.body( "id", notNullvalue()) 

.body( "origin", is("Avenida Paulista, 1000")) 

.body( "destination", is("Avenida Ipiranga, 100")) 


-body("status", is("CREATED") ) 
.body(" links.passenger.title", is("Alexandre Saudate") ) 


Vamos criar o teste da solicitação de viagens em si. É uma API 
disponível na URL /travelRequests/nearby , que recebe um 
query param chamado currentAddress através do método GET. 
Esta API retorna o código de status 200 com um array. Por conta 
desse fator, vamos adicionar no começo de cada string o valor 

[0] , que será equivalente ao primeiro elemento do array de 
resposta. Exceto por esse detalhe, o restante das validações será 
essencialmente o mesmo: 
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given() 
.get("/travelRequests/nearby?currentAddress=Avenida Paulista, 
900") 
. then() 
. statusCode(200) 
-body("[0].id", notNullValue() ) 
-body("[0].origin", is("Avenida Paulista, 1000")) 
.body("[0].destination", is("Avenida Ipiranga, 100") ) 
.body("[@].status", is("CREATED") ) 


Por ora, os testes ja funcionam. Como realizamos a 
configuração do Failsafe antes, podemos executar os nossos 
testes com o comando mvn clean verify . Esse método vai fazer 
com que os testes de integração sejam executados. Nos logs, deve 
aparecer algo semelhante às seguintes linhas (isoladamente): 

[INFO] Tests run: 1, Failures: O, Errors: O, Skipped: O, Time ela 


psed: 9.885 s - in app.car.cap05. interfaces. incoming. TravelReques 
tAPITestIT 


[INFO] Tests run: 1, Failures: O, Errors: O, Skipped: O, Time ela 
psed: 0.041 s - in app.car.cap05.interfaces.incoming.PassengerAPI 
TestIT 


Para deixar nossos testes mais confiáveis, vamos fazer com que 
os testes da API de solicitação de viagens utilizem os dados que 
retornam da criação do passageiro, em vez de utilizar o ID 
hardcoded. Para isso, vamos utilizar uma técnica conhecida como 
placeholders - ou seja, declarar trechos dentro do arquivo que são 
feitos com o propósito de serem modificados. Para criar um 
placeholder, vamos abrir novamente o arquivo 

create new request.json e alterá-lo para que o ID do 
passageiro seja a String {{passengerId}} : 
{ 

"nassengerId":"{{passengerId}}", 


"origin":"Avenida Paulista, 1000", 
"destination": "Avenida Ipiranga, 100" 
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Em seguida, vamos criar uma sobrecarga do método 
loadFileContents que aceite um mapa contendo os valores que 
devem ser utilizados no lugar dos placeholders. Esse método vai 
chamar o método loadFileContents original e depois executar 
um laço onde, para cada chave do mapa encontrada no arquivo, 
será feita uma reposição com seu respectivo valor. Desta forma, o 
método novo vai ficar assim: 


public static String loadFileContents(String fileName, Map<String 
, String> replacements) { 
String fileContents = loadFileContents(fileName); 


for (Map.Entry<String, String> entry : replacements.entryset() 


DL 
fileContents = fileContents.replace("((" + entry.getkey() + 


"}}", entry. getValue()); 
} 


return fileContents; 


Note que o código leva em consideração a delimitação do 
placeholder, ou seja, as strings {{ e 3). 


Agora, vamos alterar a classe TravelRequestAPITestIT para 
que extraia o ID do passageiro e popule a requisição para a API de 
requisição de viagens com ele. Para isso, na chamada que é feita 
para a API de passageiros, precisamos chamar os métodos 

extract () (para inicializar a extração de dados da resposta), 
body() (para informar que os dados extraídos estão no corpo da 
resposta), jsonPath() (para dizer que vamos extrair usando 
JSON Path) e getString (para recuperar o conteúdo e realizar a 
adaptação, se necessária, para String). Este último recebe como 
parâmetro uma String JSON Path e retorna o valor desejado. A 
chamada para a API de passageiros fica assim: 
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String passengerId =given() 
.contentType(ContentType. JSON) 
. body(loadFileContents("/requests/passengers_api/create_new_pa 
ssenger.json") ) 
.post("/passengers") 
. then() 
. statusCode(200) 
.body( "id", notNullvalue()) 
.body( "name", is("Alexandre Saudate")) 
.extract() 
. body() 
.jsonPath().getString("id") 


O próximo passo é criar um mapa e populá-lo com a variável 
retornada e a String passengerId (ou seja, nosso placeholder): 


Map<String, String> data = new HashMap<>(); 
data. put("passengerId", passengerId); 


Vamos adaptar a chamada para a API de requisições de viagens 
para utilizar estes placeholders, passando o mapa data como 
parâmetro para o método loadFileContents : 


given() 
.contentType(ContentType. JSON) 
.body(loadFileContents("/requests/travel requests api/create n 
ew request.json", data)) 
.post("/travelRequests") 
.then() 
.statusCode(200) 
.body( "id", notNullvalue()) 
.body( "origin", is("Avenida Paulista, 1000")) 
.body( "destination", is("Avenida Ipiranga, 100")) 
-body("status", is("CREATED") ) 
.body("_links.passenger.title", is("Alexandre Saudate") ) 


Vamos também aproveitar que estamos fazendo estas 
melhorias e reforçar o teste da recuperação das viagens passando 
para a verificação o ID da requisição de viagem criada. Faremos a 
extração desse ID de forma bastante semelhante ao que fizemos na 
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extração do ID do passageiro, exceto o último método. Vamos 
passar a utilizar o método get() , que realiza cast automático 
para o tipo do dado JSON (no caso dos ID's, este é um Integer): 


Integer travelRequestId = given() 
.contentType(ContentType. JSON) 
-body(loadFileContents("/requests/travel requests api/create n 

ew request.json", data)) 

.post("/travelRequests") 

.then() 

.statusCode(200) 

.body( "id", notNullvalue()) 

.body( "origin", is("Avenida Paulista, 1000")) 
.body( "destination", is("Avenida Ipiranga, 100")) 
.body( "status", is("CREATED")) 
.body("_links.passenger.title", is("Alexandre Saudate")) 
.extract() 

.jsonPath() 

«get ("id") 


Finalmente, vamos alterar a última chamada para a API para 
comparar o ID da viagem recuperada com o ID da requisição 
recém-criada: 


given() 
.get("/travelRequests/nearby?currentAddress=Avenida Paulista, 
900") 
. then() 
. statusCode(200) 
.body("[0].id", is(travelRequestId) ) 
-body("[0].origin", is("Avenida Paulista, 1000")) 
-body("[0].destination", is("Avenida Ipiranga, 100") ) 
.body("[0].status", is("CREATED") ) 


O código finalizado da nossa classe de testes fica assim: 
package app.car.cap05. interfaces. incoming; 


import com.github.tomakehurst.wiremock.WireMockServer; 
import com.github.tomakehurst.wiremock.core.WireMockConfiguration 
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r 

import 
import 
import 
import 
import 
import 
import 
import 


io.restassured.RestAssured; 
io.restassured.http.ContentType; 
org.junit.jupiter.api.BeforeEach; 
org.junit.jupiter.api.Test; 
org.springframework.beans.factory.annotation.Autowired; 
org.springframework.boot.test.context.SpringBootTest; 
org.springframework.boot.web.server.LocalServerPort; 
org.springframework.cloud.contract.wiremock.AutoConfigurewW 


ireMock; 


import 
import 
import 


import 
import 
import 
import 
import 
ents; 


org.springframework.test.context.ActiveProfiles; 
java.util.HashMap; 
java.util.Map; 


static com.github.tomakehurst.wiremock.client.WireMock.*; 
static io.restassured.RestAssured.given; 

static org.hamcrest.Matchers.is; 

static org.hamcrest.Matchers.notNullValue; 

static app.car.cap05.infrastructure.FileUtils.loadFileCont 


@SpringBootTest(webEnvironment = SpringBootTest.webEnvironment. RA 
NDOM_PORT ) 

@AutoConfigurewWireMock(port = WireMockConfiguration.DYNAMIC_PORT ) 
@ActiveProfiles("test") 


public 


class TravelRequestAPITestIT { 


@LocalServerPort 
private int port; 


@Autowired 
private WireMockServer server; 


@BeforeEach 
public void setup() { 


RestAssured.port = port; 


@Test 


public void testFindNearbyTravelRequests() { 


setupServer(); 

String passengerId =given() 
.contentType(ContentType. JSON) 
.body(loadFileContents("/requests/passengers_api/create_ 
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new_passenger.json")) 
.post("/passengers") 
.then() 
.statusCode(200) 
.body( "id", notNullValue()) 
.body( "name", is("Alexandre Saudate")) 
.extract() 
.body() 
.jsonPath().getString("id") 


r 


Map<String, String> data = new HashMap<>(); 
data. put("passengerId", passengerId); 


Integer travelRequestId = given() 
.contentType(ContentType. JSON) 
-body(loadFileContents("/requests/travel requests api/cr 

eate new request.json", data)) 
.post("/travelRequests") 
.then() 
.statusCode(200) 
.body( "id", notNullValue()) 
.body( "origin", is("Avenida Paulista, 1000")) 
.body( "destination", is("Avenida Ipiranga, 100")) 
.body( "status", is("CREATED")) 
.body("_links.passenger.title", is("Alexandre Saudate")) 
.extract() 
.jsonPath() 
.get("id") 


r 


given() 

.get("/travelRequests/nearby?currentAddress=Avenida Paul 
ista, 900") 

. then() 

. statusCode(200) 

-body("{O].id", is(travelRequestId) ) 

-body("[0].origin", is("Avenida Paulista, 1000")) 

-body("[0].destination", is("Avenida Ipiranga, 100") ) 

-body("[0].status", is("CREATED") ) 


} 


public void setupServer() { 
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server. stubFor (get (urlPathEqualTo("/maps/api/directions/jso 


n")) 


-withQueryParam("origin", equalTo("Avenida Paulista, 900 


)) 


.withQueryParam( "destination", equalTo("Avenida Paulista 
, 1000")) 

.withQueryParam("key", equalTo("chaveGoogle") ) 

.willReturn(okJson(loadFileContents("/responses/gmaps/sa 
mple_response.json"))) 


); 
} 


Conclusão 


Neste capítulo, nós vimos como criar testes de contrato 
utilizando dois novos frameworks, o REST Assured e o WireMock. 
Enquanto um deles vai atuar na frente da nossa API, realizando 
requisições para ela, o outro vai atuar na retaguarda, sendo 
invocado pelo sistema que construímos. Ambos desempenham um 
papel muito importante na criação de APIs, que é a garantia de 
qualidade e de funcionamento adequado. 


Pouco a pouco, estamos caminhando rumo à construção de 
uma API mais robusta, semelhante a uma API do mundo real. 
Alguns passos interessantes podem ser vislumbrados adiante, 
como a adição de uma camada de segurança - podemos permitir, 
por exemplo, que apenas motoristas autenticados na plataforma 
sejam capazes de listar as solicitações que estão próximas. 


Vamos em frente? 
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CaPiTULO 6 


SEGURANCA 


"A dúvida é o princípio da sabedoria.” - Aristóteles 


Com as nossas APIs já um pouco mais desenvolvidas, vamos 
tratar agora de aspectos relacionados à segurança. Dessa forma, 
vamos poder garantir que elas serão utilizadas da maneira desejada 
e somente pelas pessoas a quem se destinam. 


6.1 CONHECENDO HTTPS 


O HTTPS ( Hyper Text Transfer Protocol Secure - 
protocolo de transferência de hipertexto seguro) é a peça mais 
fundamental de proteção de dados que temos na web. De fato, 
nenhum dos sistemas de autenticação e autorização que temos 
para nossas APIs está completo sem o uso de HTTPs. Por isso, é 
fundamental que conheçamos primeiro essa peça fundamental 
para podermos compreender com profundidade o uso dos 
algoritmos que vamos ver mais à frente. 


Em primeiro lugar, vamos elencar os motivos pelos quais 
usamos HTTPS. Estes são 3: 


e Privacidade 
e Integridade 
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e Identificação 


Quando falamos em privacidade, quer dizer que um atacante 
não pode visualizar suas mensagens. Por exemplo, digamos que 
você está fazendo uma solicitação de viagem no aplicativo da 
C.A.R. para ir a um show. Este show é de um tipo musical de gosto 
duvidoso, então você não quer que ninguém saiba que você está 
indo vê-lo. A quebra de privacidade diz respeito à capacidade de 
um atacante de interceptar a requisição e descobrir o conteúdo. 


Como UM ATACANTE INTERCEPTA UMA MENSAGEM? 


Na verdade, é surpreendentemente fácil interceptar 
mensagens. Existe toda uma classe de softwares chamados de 
sniffers, que são sistemas especialistas em captura de pacotes 
através de redes. Uma vez que um atacante esteja de alguma 


forma conectado à rede, basta ligar o sniffer (por exemplo, o 


Wireshark - https://www.wireshark.org/) e começar a 
capturar e decodificar os pacotes. 





O segundo ponto, integridade, quer dizer que um atacante não 
modificou sua mensagem. Então você tem a garantia de que está 
indo para o show, e não para um encontro de pessoas interessadas 
em canto mongol gutural. 


O terceiro ponto, identificação, mostra que a partir da 
assinatura digital do servidor você tem a garantia da identidade 
dele. Em outras palavras, você tem a certeza de que está fazendo a 
requisição no aplicativo C.A.R. e não no daquela empresa que 
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começa com U, por exemplo. 


A maneira como HTTPS trabalha previne esses três problemas 
através de uma camada de segurança SSL/TLS. Mas para entender 
como essa camada funciona, vamos falar um pouco sobre 
criptografia. A criptografia engloba o uso de técnicas para 
comunicação segura na presença de terceiros. Duas dessas técnicas 
mais comuns referem-se ao uso de criptografia simétrica ou 
assimétrica. 


A criptografia simétrica refere-se ao uso de uma chave 
simétrica para o envio de mensagens. É como se você fosse enviar 
uma carta para um amigo e, para que ninguém inspecione o 
conteúdo da carta, você a coloca dentro de uma caixa e então 
tranca. Para que seu amigo abra a caixa, ele precisa ter uma cópia 
da chave. Isso traz grandes problemas para gerenciar, já que, se 
você tiver um grande número de amigos, é bem provável que o 
gerenciamento dessas chaves se torne um tanto quanto complicado 
- se uma delas vazar, pode comprometer as outras. 


Já a criptografia assimétrica faz uso de duas chaves, uma 
pública e uma privada. A chave pública é utilizada para 
criptografar as mensagens, e a chave privada, para descriptografar. 
No exemplo da carta dentro da caixa, o processo fica mais 
complicado, porém mais seguro. Se você quer mandar a carta, você 
coloca a mensagem dentro da caixa e a tranca utilizando a chave 
pública do seu amigo. Apenas ele poderá abrir a caixa, usando a 
chave privada dele. 


Mas como você faz para descobrir essa chave? 


A descoberta de chaves faz parte de um procedimento do 
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HTTPS chamado de handshake. O handshake é iniciado pelo 
cliente, que envia para o servidor o conjunto de algoritmos de 
criptografia que entende (também conhecido como cipher suite). O 
servidor responde com seu certificado e a chave pública 
correspondente a um dos algoritmos enviados pelo cliente. 


UM ALERTA! 


A explicação que dou aqui sobre criptografia simétrica e 
assimétrica (e sobre o processo de handshake como um todo) 
é extremamente simplificada. Existem vários outros detalhes 


nessa questão que achei melhor deixar de fora, por entender 


que não se trata do escopo deste livro. Esta é uma visão 
superficial contendo apenas o necessário que precisamos 
saber para implementar HT'TPS num serviço REST. 





O certificado é um dos componentes principais aqui. É ele 
quem faz o papel de identificar o site de forma segura, através do 
uso de uma cadeia de confiança. Para explicar a cadeia de 
confiança, vou usar uma analogia: suponha que você está em uma 
festa com seu amigo, João. João é um dos seus melhores amigos, e 
você confia nele. João lhe apresenta um dos amigos dele, José. 
Você não conhecia José antes, mas já que João confia nele, e você 
confia em João, então você também confia em José. Por 
consequência, se José porventura lhe apresenta alguém, você 
também confia nessa pessoa porque você confia em José. 


O funcionamento dos certificados é semelhante: 
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e O computador (ou dispositivo móvel, ou qualquer outro 
tipo de dispositivo) vem com alguns certificados já pré- 
instalados nele; 

e Estes certificados são das chamadas autoridades 
certificadoras, ou seja, são certificados de empresas 
reconhecidas pelo fabricante do sistema operacional como 
sendo seguras (confiáveis) e capazes de realizar a 
verificação de que outros sites também são seguros; 

e Quando entramos em um site que é acessado via HTTPS, 
este site fornece um certificado que pode ter sido assinado 
por uma autoridade certificadora. Em outras palavras, esta 
autoridade certificadora endossa este certificado de forma 
que ele também passa a ser confiável. 


Dito isso, é necessário ter conhecimento de que existe também 
o conceito de certificado autoassinado, que são certificados que 
não são assinados por nenhuma autoridade certificadora. Estes 
certificados também proveem a capacidade de oferecer privacidade 
e integridade dos dados, mas são falhos na capacidade de 
identificação do site pois não contam com a capacidade da cadeia 
de confiança. Certificados autoassinados são úteis para sistemas 
em fase de testes e redes internas, mas você deve evitar usá-los em 
APIs ou sites abertos para o mundo. 


6.2 IMPLEMENTANDO HTTPS NA NOSSA API 


Vamos criar um certificado autoassinado e implantá-lo na 
nossa API. O Java já fornece uma ferramenta própria para geração 
de certificados, o keytool. Trata-se de uma ferramenta de linha de 
comando disponível na pasta bin da JDK. Na realidade, o 
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keytool trabalha com arquivos que são conhecidos por 
armazenar varios objetos relacionados a criptografia, sendo os 
certificados apenas um desses objetos. Vamos usar o keytool 
para gerar um arquivo do tipo PKCS12 , que é um formato 
interoperável para se trabalhar com várias linguagens. 


Para gerar o certificado, precisamos escolher um algoritmo de 
criptografia. Esse algoritmo é o que vai ser usado para realizar a 
proteção dos dados, e o certificado vai conter a chave dele. Vários 
algoritmos estão disponíveis, então vamos escolher o RSA - um 
bom algoritmo de criptografia assimétrica. Por escolher este 
algoritmo, também precisamos definir o tamanho da chave 
(quanto maior o tamanho, mais forte o algoritmo é, e maior o 
tempo necessário para decodificação). Vamos escolher 2048 para o 
tamanho (que é o padrão). Também precisamos determinar um 
prazo de validade para o certificado. O keytool recebe esse prazo 
em dias - vamos usar 3650 como uma aproximação para 10 anos. 


Os últimos parâmetros que precisamos determinar são 
relacionados ao alias do certificado (é como se fosse o nome do 
arquivo dentro de um arquivo zip ), o nome do arquivo e a 
senha. 


O comando fica assim: 
keytool -genkeypair -alias car -keyalg RSA -keysize 2048 -storety 
pe PKCS12 -keystore keystore.p12 -validity 3650 -storepass restbo 
ok 


Listando cada parâmetro: 


e genkeypair determina o que esse comando está fazendo 
(vale lembrar que o keytool é uma ferramenta que tem 
diversas funcionalidades diferentes); 
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alias vai gerar o nome do certificado dentro do arquivo. 

No caso, 0 nome sera car ; 

e keyalg é o nome do algoritmo, ou seja, RSA ; 

e keysize é o tamanho da chave criptográfica (2048); 

e storetype éo tipo de arquivo que será gerado (ou seja, o 
PKCS12 ); 

e keystore é o nome do arquivo físico que será gerado 

( keystore.p12 ); 


validity determina o tempo de validade do certificado 
(3650 dias); 
storepass é a senha para abertura do arquivo PKCS12 


(no caso, restbook ). 


Este comando deve ser executado na pasta bin da JDK. Uma 
vez executado, uma série de perguntas deverão ser respondidas. 
Tenha apenas o cuidado de inserir localhost como resposta da 
primeira. As seguintes, pode responder da maneira como preferir - 
ou mesmo deixar em branco, como eu fiz no meu caso: 
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/bin/bash x /bin/bash x 








Figura 6.1: Geração do certificado autoassinado 


POR QUE COLOCAMOS LOCALHOST COMO CN? 


Como o certificado serve como identificador do site sendo 
acessado, é uma convenção da internet colocar o CN como o 
endereço onde o site está hospedado. Esta convenção deve 
sempre ser respeitada, pois alguns clientes podem apresentar 


problemas para acessar a API se o CN não corresponder ao 
host. 





Agora, vamos mover o arquivo gerado para a pasta 
src/main/resources do nosso projeto. Vamos em seguida 
configurar o Spring Boot para habilitar o HTTPS. Para isso, 
precisamos colocar as seguintes configurações no arquivo 
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application.properties : 


server.ssl.key-store=classpath: keystore. p12 
server.ssl.key-store-password=restbook 
server.ssl.key-store-type=PKCS12 
server.ssl.key-alias=car 


A primeira configuração é relacionada à localização do arquivo 
keystore. p12 . Isso indica para o Spring Boot que o arquivo está 
na raiz do classpath da aplicação. O segundo parâmetro é a senha 
do arquivo (que nós determinamos no parâmetro -storepass do 
keytool ). O terceiro parâmetro é o tipo do arquivo, ou seja, 
PKCS12 . Finalmente, o último parâmetro é o nome do objeto que 
estamos procurando dentro do arquivo (que nós determinamos no 
parâmetro -alias do keytool ). 


Colocadas todas essas configurações, vamos inicializar o 

sistema e abrir uma API do sistema, digamos, 

http://localhost:8080/drivers . Uma mensagem semelhante 
à seguinte deve ser exibida: 


Bad Request 
This combination of host and port requires TLS. 


Isso indica que o nosso servidor rejeitou a requisição por não 
estar com HTTPS. Vamos mudar o endereço para 
https://localhost:8080/drivers (observe que mudamos para 
https no início). Como eu uso Chrome, um alerta assim foi 
emitido: 
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fe 


Your connection is not private 


Attackers might be trying to steal your information from localhost (for example, 
Passwords, messages, or credit cards). Learn more 


NET:ERR CERT AUTHORITY INVALID 


O Help improve Safe Browsing by sending some system information and page content to Google 





Privacy policy 





| Hide advanced 


This server could not prove that it is localhost; its security certificate is not trusted by 
your computer's operating system. This may be caused by a misconfiguration or an 
attacker intercepting your connection. 


Proceed to localhost (unsafe) 





Figura 6.2: Chrome pedindo para liberar a request 


Esse alerta significa que o Chrome entende que o certificado é 
autoassinado e isso não é prova da identidade do servidor. Clique 
em Proceed to localhost (ou equivalente se você usar outro 
browser). Observe que agora a API executa corretamente e um 
alerta aparece no canto superior. 


Vamos agora verificar as requisições no Postman. Tomando a 
API de salvar passageiro, por exemplo, clique no botão Send para 
enviar a requisição como está. Observe que a API deve retornar 
um código HT'TP 400 e a mensagem indicando que a requisição 
deve passar por um canal seguro: 
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Postman 





4 ser post pur post SX pes ser > + 


+ Salvar passageiro EJ comments (0) Examples(0) » 














POST ~ http://localhost:8080/passengers Save + 
(9) Body @ Cookies Code 
none form-data x-www-form-urlencoded ® raw binary GraphQL BETA iso ” Beautify 
-U x 
“Alexandre Saudate 
35 } 
Body (2) us! 400 Bad Request Time: 516ms 1548 Save Response + 
Pretty Me ed Ex ma 
1 Bad Request 
2 This combination of host and port requires TLS. 
ma a © Bootcamp Build Browse H E 


Figura 6.3: Postman apresentando a mensagem de erro do servidor 


Porém, se trocarmos o host para HTTPS, o erro fica até pior: 
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Postman 


y & Invite MD 





No Environment - og 


POST v https://localhost:8080/passengers Save v 


m Body @ 








none form-data x-www-form-urlencoded  @ raw binary Graphqu SETA 


“name”: “Alexandre Saudate” 


Could not get any response 


There was an error connecting to https://localhost8080/passenge 


Why this might have happened: 


» The server couldn't send a response: Ensure that the backend Is working properly 


verification’ in Settings > General 





certific 





* Self-signed SSL certificates are being blocked: Fix this by turning off " 





* Proxy configured incorrectly Ensure that proxy is configured correctly in Settings > Proxy 





* Request timeout: Change request timeout in Settings > General 
Browse fl a 


a © Bootcamp 


Figura 6.4: Postman mostrando uma nova mensagem de erro 


Isso acontece porque o Postman valida os certificados. Como 
nosso certificado é autoassinado, ele se recusa a prosseguir com a 
requisição ainda na fase de handshake. Para mudar isso, clique no 


menu superiorem File > Settings : 
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General 





REQUEST 


Trim keys and values in request body 
New Cade Generation Mode 

SSL certificate verification 

Always open requests in new tab 
Always ask when closing unsaved tabs 
Language detection 

Request timeout in ms (0 for infinity) 


Max response size in MB (0 to infinity) 


Automatically persist variable values 


WORKING DIRECTORY 


0 
50 


Eon 


HEADERS 


d no-cache header 





Send Postman Token header 


Retain headers when clicking on links 





Automatically follow redirects 





d anonymous usage data to Postman 


USER INTERFACE 


Editor Font Si 





(px) 
Two-pane view 

Show icons with tab names 
Variable autocomplete 


Open Launchpad 


Figura 6.5: Desmarcando verificação SSL 


Deixe a opção SSL certificate validation 
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@) on 
Oo 


g on 
O on 


na posição 


OFF e teste novamente. Agora, você deve ter o resultado esperado: 
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Postman 


v & Invite G 





POST v  https://localhost:8080/passengers 





no Boys Cookies Code 
none form-data xwww-form-urlencoded 4 raw binary GraphqL SETA json ~» 


“name”: “Alexandre Saudate” 


Body n) (3) tatus: 2000K Time: 1082ms Size 1518 Save Response v 
Pretty MEIN N 3 maq 
a a 

cido: 1 


x 
3 "name": “Alexandre Saudate" 
4 


I 4 


O 24 a =) Bootcamp Build Browse E & 


Figura 6.6: Requisição funcionando via Postman 


6.3 INCLUINDO AUTENTICAÇÃO BÁSICA 


Um dos mecanismos mais básicos da segurança da informação 
também é a prevenção de acesso a informações por pessoas não 
autorizadas. Por exemplo: na sua casa, provavelmente há uma 
porta. Essa porta tem uma chave. Apenas aqueles que têm uma 
cópia da chave podem acessar a casa, de forma que a porta previne 
o acesso não autorizado. 


O acesso a APIs (em sua forma mais simples) funciona da 
mesma forma. Um usuário possui uma combinação de usuário e 
senha, de forma que esta combinação é responsável por fazer a 
autenticação do usuário, ou seja, verificar se ele é conhecido pelo 
sistema, se essa combinação é válida etc. Uma vez autenticado, é 
feito o processo de autorização, uma verificação de quais recursos 
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o usuário pode acessar com essa combinação de usuário e senha. 
Voltando ao exemplo da casa, é como se abrir a porta fosse o 
processo de autenticação, e a autorização é como se a pessoa não 
pudesse acessar determinados cômodos da casa, mesmo tendo 
aberto a porta da frente. 


Para realizar essa proteção de dados, vamos incluir um novo 
framework no projeto, o Spring Security . Para isso, basta 
incluir o seguinte na seção de dependências do projeto, no 

pom.xml : 
<dependency> 
<groupId>org.springframework. boot</groupId> 
<artifactId>spring-boot-starter -security</artifactId> 
</dependency> 

Note que não é necessário incluir a versão da dependência, pois 
o projeto já é gerenciado pelo Spring Boot e ele já faz a inclusão da 
versão correta, de forma que todo o conjunto opera em harmonia. 


Agora, vamos criar um pacote de configurações do projeto 
chamado config e, dentro dele, uma classe chamada 


SecurityConfig : 
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» &.mvn 
y src 
v main 
y java 
v Emapp 
v car 
7 Ex cap06 
r config 
© SecurityConfig 
7 domain 
© Driver 
® DriverRepository 
‘© Passenger 
® PassengerRepository 
‘© TravelRequest 
® TravelRequestRepository 
‘© TravelRequestStatus 
© TravelService 
> Em interfaces 
‘© Cap06Application 
7 BE resources 
static 
templates 
ii application.properties 
b keystore.p12 


Figura 6.7: Nova estrutura do projeto 


No Spring Boot, existe uma anotação chamada 
@Configuration , que determina que esta classe é responsável 
por prover objetos que estarão disponíveis para todo o contexto da 
aplicação. Além disso, podemos anotar essa classe com outras 
anotações do Spring que também vão habilitar ou desabilitar certos 
aspectos do sistema. Assim sendo, vamos anotá-la com 
@Configuration e depois com a anotação 
@EnablewebSecurity , que vai ser responsável por habilitar 
efetivamente a segurança das nossas APIs: 


package app.car.cap06.config; 
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import org.springframework.context.annotation.Configuration; 
import org.springframework.security.config.annotation.web.configu 
ration.EnablewebSecurity; 


@Configuration 
(QEnablewebSecurity 
public class SecurityConfig { 


O próximo passo é configurar o nosso sistema de segurança 
para verificar o funcionamento. Como existem muitos aspectos a 
serem levados em consideração, o Spring nos fornece uma classe 
chamada webSecurityConfigureradapter . O propósito desta 
classe é fornecer alguns métodos para serem sobrescritos com a 
configuração desejada e também manter as configurações padrões 
para o restante. Vamos fazer com que a nossa classe 
SecurityConfig estenda WebSecurityConfigurerAdapter : 


package app.car.cap06.config; 


//Outros imports omitidos 
import org.springframework.security.config.annotation.web.configu 
ration.WebSecurityConfigurerAdapter; 


@Configuration 
(QEnablewebSecurity 
public class SecurityConfig extends WebSecurityConfigurerAdapter 


{ 


Desta forma, temos acesso ao método mais importante da 
classe WebSecurityConfigurerAdapter , que é o configure 
Este método é sobrecarregado algumas vezes, de forma que o que 
queremos é o que recebe HttpSecurity como parâmetro. Vamos 
então sobrescrever esse método para iniciar a configuração. O 
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método sobrescrito fica assim: 
package app.car.cap06.config; 


//Outros imports omitidos 
import org.springframework.security.config.annotation.web. builder 
s.HttpSecurity; 


@Configuration 
(QEnablewebSecurity 
public class SecurityConfig extends WebSecurityConfigurerAdapter 


{ 


@Override 
protected void configure(HttpSecurity http) throws Exception { 


} 


Agora vamos iniciar a configuração de segurança do nosso 
projeto. O primeiro passo é desabilitar a proteção a um ataque 
abreviado como CSRF (que significa Cross-Site Request Forgery, 
que traduzo como "Forja de requisições entre sites”). Primeiro 
vamos entender como ele funciona e por que desabilitá-lo. 


A documentação do Spring detalha o CSRF com exemplos 
(disponível em https://docs.spring.io/spring- 
security/site/docs/5.2.1.RELEASE/reference/htmlsingle/#csrf). 

Vou dar aqui uma explicação resumida sobre o problema apenas 
para contextualizar o porquê de desabilitarmos a proteção. 


Quando entramos em um site qualquer (digamos, do banco) 
precisamos fornecer o usuário e senha apenas uma única vez, ao 
acessar o site. Como acontece, então, de o site do banco nos 
“reconhecer” enquanto vamos navegando por outras páginas? 
Através dos cookies. Cookies são pequenos arquivos de texto que 
são “devolvidos” para o site conforme vamos navegando naquele 
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dominio, e através do conteúdo do cookie o site do banco nos 
reconhece, dispensando a necessidade de nos autenticarmos 
novamente. 


Os cookies são fornecidos de volta apenas para os sites que os 
fornecem, de forma que os cookies que recebemos de um site 
http://abc.com.br não são repassados para um site 
http://xyz.com.br . No entanto, o ataque de CSRF não precisa 
disso, pois um site malicioso pode incluir um formulário 
semelhante ao seguinte: 


<form method="post" action="https://banco.com/transferencia"> 
<input type="hidden" name="quantia" value="100.00"/> 
<input type="hidden"name="conta" value="numeroDaContaMaliciosa 
/> 
<input type="submit" value="Ganhe Dinheiro Facil, Clique Aqui 
Para Saber Como!"/> 
</form> 


Isso vai fazer com que um botão escrito Ganhe Dinheiro 
Facil, Clique Aqui Para Saber Como! apareca na tela. 
Quando um visitante inocente entrar no site e clicar no botao, ele 
fará uma requisição legítima para o endereço 

https://banco.com/transferencia . Por ser uma requisição 
legítima, o browser entende que pode fornecer os cookies corretos 
e, assim, dispensar a autenticação/autorização necessária. O ataque 
foi executado com sucesso. 


A proteção que o Spring Security oferece para esse ataque pode 
ser resumida em incluir um parâmetro extra nas requisições que é 
fornecido para cada requisição. O valor desse parâmetro é aleatório 
e gerado pelo servidor, sendo que um atacante não teria como 
adivinhar o valor dele. Já um visitante legítimo sim, já que a cada 
página acessada o servidor devolveria um novo valor para este 
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parâmetro, controlando a navegação. 


Quando falamos de APIs REST, podemos dispensar essa 
proteção. Isso porque o ideal em uma API REST é que ela seja 
stateless, ou seja, sem estado. Uma API sem estado não guarda 
informações sobre o visitante (ou seja, não usa cookies). Dessa 
forma, todo e qualquer acesso requisita os cabeçalhos de 
autenticação necessários, tornando as APIs automaticamente 
imunes ao CSRF. 


Desta forma, vamos executar dois passos: desligar a proteção 
contra CSRF na API (ou seja, desativar a necessidade de fornecer 
esse parâmetro extra) e também desligar o gerenciamento de 
sessões, de forma que o nosso servidor não vai mais devolver 
cookies para nenhum cliente. 


Para desligar a proteção contra CSRF, invocamos o método 
csrf() e depois o método disable() : 


protected void configure(HttpSecurity http) throws Exception { 
http.csrf().disable(); 


Para desligar o gerenciamento de sessões, invocamos o método 

sessionManagement () e depois o método 

sessionCreationPolicy , passando como parâmetro 
SessionCreationPolicy.STATELESS : 


import org.springframework.security.config.http.SessionCreationPo 

licy; 

@Override 

protected void configure(HttpSecurity http) throws Exception { 
http.csrf().disable(); 


http.sessionManagement ( ) 
.sessionCreationPolicy(SessionCreationPolicy.STATELESS) ; 
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Depois dessa preparação, vamos incluir autenticação básica nas 


nossas APIs. Essa autenticação funciona da seguinte forma: 


e O primeiro passo é juntar o usuário e senha, separados por 


dois-pontos. Por exemplo, se o usuário for admin ea 

senha for 1234 , teremos admin:1234 . 

Depois, passamos esse valor por um algoritmo chamado de 
Base64 , que consiste na codificação de dados em um 

conjunto de apenas 64 caracteres (daí o nome). Nosso 

usuário e senha de exemplo ficariam assim: 
YWRt aW46MTIZNA== . 

O próximo passo é acrescentar a palavra Basic no início, 

e um espaço. No exemplo, fica Basic 

YWRtaw46MTIZNA== . 

Por último, fornecemos esse conjunto em um cabeçalho 

chamado Authorization . 


Observe que é um algoritmo muito simples e fácil de reverter 


para descobrir qual o usuário e senha utilizados. Por esse motivo, 


sempre que esse algoritmo é utilizado, é obrigatório utilizar 
HTTPS também. 


Para configurar o sistema para utilizar esse algoritmo, 


utilizamos a seguinte sequência de métodos: 


authorizeRequests()  - para iniciar o sistema de 
configuração de segurança; 
anyRequest() - para realizar a configuração sobre todas 
as URLs, com quaisquer métodos HTTP; 
authenticated() - para requisitar autenticação; 
and() - para complementar a configuração; 
httpBasic() - para utilizar o algoritmo de autenticação 
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básica que vimos acima. 


Assim, nosso método completo fica assim: 


@Override 


protected void configure(HttpSecurity http) throws Exception { 
http.csrf().disable(); 


http.sessionManagement ( ) 
.sessionCreationPolicy(SessionCreationPolicy.STATELESS) ; 


http 


.authorizeRequests() 
.anyRequest() 
.authenticated() 


«and() 


.httpBasic(); 


Isso conclui a configuração do sistema para requerer os 


usuários. Mas e quanto aos usuários em si, onde estão? Enquanto a 


criação de usuários não fica pronta, o Spring Security nos fornece 


um usuário para realizarmos os testes. Para verificar onde está o 


usuário e senha, basta inicializar o sistema para visualizar algo 


semelhante ao seguinte: 





l 
[i 
[i 
1 
Es] 
1 
| 
{ 


WARN 
INFO 6454 +++ | 


2010-12-26 17:01:38.452 


Using generated security password 


INFO 6454 ++ | 
INFO 6454 «=. | 
INFO 6454 --+ | 
INFO 6454 --- | 
INFO 6454 


2010-12-76 17:01:38.565 
2019-12-26 17:01:38.717 
2019-12-26 17:0) 
2019-12-26 17:01:39.495 
2819-12-76 17:01 


restartedMain) 0.5.b.a.n2.H2ConsolemutoContiquration 
restartesmain) o hibernate, jpa. internal util. LogHelper 
restartedMain} org.hibernate. Version 

restarte@Main} o hibernate, annotations. common. Version 
restartesMain) org.hibernate.dialect Dialect 
restartedMain! o.h.e.t.j,p.i,JtaPlatforelnitiator 
restartemain) | LocalContainerEntitymanagerFactoryBoun 
restortedMain) 0.5.b.d.a.OptionalLiveReloadServer 


restartedain] .5.s.UserDetailsServicedutoConfiguration 


85240402- f10d-49f4-0bbt-398e9ede3937 


restartedMain] 0.s.s.web.DefaultSecurityFilterthain 
restartedmain] 0.3. concurrent. ThreadPoolTaskExecutor 
restartedMain) 0.5.b.w.embedded. tomcat. ToncatmebServer 
restartedMain] app.car.cap06. Cap@GApplication 


+++ [nio-89@8-exec-4} 0.a.¢.c.C. (Tomcat). [tocalhost)|.[/] 


; WZ console available at “/h2-console’, Database available 
Hansa, 


1204: Processing Persistenceunitinto [names default] 


: M9904122: Hibernate Core (5.4.6.Final) 


1: Hibernate Commons Annotations (5.1.0.Final) 


+ W440008400: Using dialect: org hibernate. dialect .W2Dialect 
7 HHHO00490; Using JtaPlatform implementation: forg,hibernat 


Initialized JPA EntityMunagerFactory for persistence unit 


+ LaweMeload server is running on port 35729 
restartedtain] JpaiaseContiqurations2pawebContiquration : 


spring. jpa opan-in-view is enabled by default. Therefore, 


Creating filter chain; any request, lorg.springfranework.# 


: Initializing Executorservice "applicationtaskExecutor" 

: Tomcat started on portis}: BOSS (https) with context path 
+ Started CapO6Application in 7.005 seconds (JM running fon 
: Initializing Spring DispatcherServiet ‘dispatcherSserviet 


Figura 6.8: Senha gerada pelo Spring Security 


Observe o trecho que diz: 


Using generated security password: a524c462-f10d-49f4-8bb1-398e9e 


de3937 
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Essa é uma senha gerada aleatoriamente toda vez que o sistema 
é inicializado. Ela é associada a um usuário chamado user , e 
podemos então passá-la para testar nossas APIs. Vamos verificar 
como está a configuração e testar a nossa API de criação de 
passageiros da forma como está. Algo semelhante ao seguinte deve 
ser retornado: 


{ 
"timestamp": "2019-12-26T19:06:07.724+0000", 
"status": 401, 
"error": "Unauthorized", 
"message": "Unauthorized", 
"path": "/passengers" 
} 


Postman 


File Edit View Help 


REST - Construa API's 


v å Invite (G 
inteligentes de = a 











No Environment ` 
4 GET Post PUT post ..@ rost.O cer > + see 
+ Salvar passageiro EM comments(0) Ex 
POST > _ https:/localhost:8080/passengers 
Authorization 1 (11) e 
TYPE 
No Au X TH 1 authorization. Learn more about authorization 
Body (1) (11) atus: 401 Unauthorized Time; 43ms ze: 5388 Save 
Pretty BETA IN + 5 


1 

2 "timestamp": "2019-12-26T19:06:07.724+0000", 
3 "status": 401, 

4 "error": "Unauthorized", 

5 "message": "Unauthorized", 

6 "path": "/passengers" 

7 


U & E Er Bootcamp Bulid Browse 


Figura 6.9: Chamada feita sem autenticação 
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Observe que o código de status 401 é retornado. Sua presença 
indica que é necessário refazer a requisição passando as credenciais 
corretas. Para incluir as credenciais, temos que ir até a aba 

Authorization do Postman. No dropdown Type existem vários 
algoritmos de autenticação disponíveis; vamos escolher Basic 
Auth . Então, vamos inserir user no campo Username e 

a524c462-f10d-49f4-8bb1-398e9ede3937 (ou o equivalente no 
seu caso) no campo Password . Ao apertar Send , recebemos o 
resultado adequado: 


Postman 


File Edit View Help 


aa REST - Construa API's 


ym Invite O 
* inteligentes de i a 











No Environment À 
4 La GET POST pur post SX post 0 GET > + ve. 
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Authorization @ (12) s 
TYPE o He 18 meters h ensitive c eep th e while ir 
r l id using variable more at riat 
B Aut ~ 
The b 
aute en yot Username user 
1d about 
ri Password a524c462-f10d-49f4-8bb1-398e9ede3937 
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Figura 6.10: Chamada feita com autenticação 
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6.4 CRIANDO SISTEMA DE AUTORIZACAO 


O próximo passo na proteção do sistema é determinar quem 
pode acessar o quê. Isso quer dizer que nem todos os usuários 
poderão acessar as mesmas APIs. Para criarmos alguns contextos 
de segurança: impedir motoristas de criar novos passageiros na 
plataforma, impedir motoristas de criar novas requisições de 
viagens na plataforma etc. Assim sendo, temos um conceito 
fundamental para a área de segurança da informação, que é o de 
papéis. 


Os papéis têm a função de atribuir funções específicas para os 
usuários, de forma a agrupá-los sob essas funções e ficar mais fácil 
de determinar o que eles podem acessar. Por exemplo, fica difícil 
dizer que o usuário João não pode criar uma requisição de 
viagem, pois dessa forma teríamos que cadastrar restrições para 
todos os outros usuários, o que pode ser impraticável. Mas se 

João tiver o papel DRIVER , fica fácil pois podemos 
simplesmente delimitar que todos os que têm esse papel não 
podem criar requisições de viagens. 


Isso dito, vamos ver nesta seção como criar um sistema de 
delimitação por papéis simples, e ir evoluindo aos poucos. 


Para começar, vamos incluir a anotação 

EnableGlobalMethodSecurity na nossa classe 
SecurityConfig . Esta anotação tem a função de habilitar alguns 
modos de segurança por anotações. Vamos utilizar o modo de 
compatibilidade com a JSR-250, que é uma especificação de um 
conjunto de anotações para padronizar alguns aspectos da 
linguagem Java. Este modo de compatibilidade é acionado a partir 
do atributo jsr250Enabled : 
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import org.springframework.security.config.annotation.web.configu 
ration.EnablewebSecurity; 
//Restante dos imports omitido 


@Configuration 

@EnableWebSecurity 

@EnableGlobalMethodSecurity(jsr250Enabled = true) 

public class SecurityConfig extends WebSecurityConfigurerAdapter 


{ 
} 

Com a inclusão desta anotação, é possível utilizar a anotação 
@RolesAllowed nos métodos que queremos restringir acesso. Por 
exemplo, digamos que vamos restringir o acesso da criação de 
passageiros apenas para aqueles que têm o papel ADMIN . Vamos 
até o método createPassenger , na classe PassengerAPI , e 
então anotamos com essa anotação e o nome do papel: 


import javax.annotation.security.RolesAllowed; 


@PostMapping 
@RolesAllowed("ROLE_ADMIN") 
public Passenger createPassenger(@RequestBody Passenger passenger 


{ 


return passengerRepository.save(passenger); 


O próximo passo é configurar o Spring Security para carregar 
os usuários e seus respectivos papéis. Para fazer isso, precisamos ir 
até a classe  Securityconfig e sobrescrever o método 

configure - desta vez, o que recebe um 

AuthenticationManagerBuilder como parâmetro: 


import org.springframework. security.config.annotation.authenticat 
ion.builders.AuthenticationManagerBuilder; 


// Trecho omitido 


@Override 
public void configure(AuthenticationManagerBuilder auth) 
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throws Exception { 


Com o objeto do parâmetro auth , é possível definir várias 
formas diferentes de armazenar os usuários. No momento, para 
manter a simplicidade, vamos criar alguns usuários apenas em 
memória - posteriormente, vamos trocar esta forma de 
armazenamento. 


Para realizar a definição dos usuários, vamos utilizar a classe 
User do Spring Security. Esta classe provê um método builder, 
que por sua vez dá acesso a vários métodos que facilitam a criação 
dos usuários. Em resumo, precisamos de três informações para 
cada um deles: nome de usuário, senha e papéis. Para fins de 
comodidade, vamos criar todos com a mesma senha. Para criar a 
senha sem nenhuma criptografia (já que ela estará na memória do 
sistema, e não em nenhuma base dados), precisamos acrescentar o 
prefixo {noop} . Este prefixo é utilizado pelo Spring Security qual 
o sistema de codificação foi aplicado - no nosso caso, nenhum: 


String password = "{noop}password"; 


Para realizar a definição dos usuários, vamos precisar chamar 
os métodos username , password e roles para determinar o 
nome de usuario, senha e papéis, respectivamente. Observe que, ao 
determinar os papéis, não colocamos o prefixo ROLE - ele é 
incluído automaticamente pelo Spring Security. Assim, vamos 
criar três usuários, um chamado driver e com um papel 
DRIVER ; um chamado passenger e com um papel PASSENGER ; 
e um último chamado admin com um papel ADMIN (eu sei, 
muito criativo de minha parte): 


import org.springframework.security.core.userdetails.User; 
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//Trecho omitido 


User.UserBuilder driver = User.builder() 
.username("driver") 
. password (password) 
.roles("DRIVER"); 


User.UserBuilder passenger = User.builder() 
.username("passenger") 
.password( password) 
.roles("PASSENGER"); 


User .UserBuilder admin = User.builder() 
.username("admin") 
. password(password) 
.roles("ADMIN"); 


Agora, basta chamarmos o método 

inMemoryAuthentication e depois, o método withUser , 

passando cada uma das definições dos usuários como parâmetro. 
O método completo fica assim: 


@Override 
public void configure(AuthenticationManagerBuilder auth) 
throws Exception { 


String password = "{noop}password"; 


User.UserBuilder driver = User.builder() 
.username("driver") 
. password(password) 
.roles("DRIVER"); 


User.UserBuilder passenger = User.builder() 
.username("passenger") 
.password(password) 

.roles("PASSENGER"); 


User.UserBuilder admin = User.builder() 
. username ("admin") 
.password(password) 

.roles("ADMIN"); 
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auth. inMemoryAuthentication() 
.withUser (driver) 
.withUser (passenger) 
.withUser (admin) 


Vamos fazer o teste. Utilizando o Postman, vamos utilizar o 
usuário driver para tentar criar um novo passageiro: 
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Figura 6.11: API recusando a chamada feita com usuário não autorizado 
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Como você pode ver, a API retorna um código 403 
Forbidden quando fazemos isso. Isso significa que o usuário foi 
autenticado, mas nao autorizado. Ou seja, ele foi reconhecido 
como um usuário válido no âmbito do sistema, mas sem permissão 
para utilizar esse recurso especifico do sistema. 


Vamos trocar para o usuário admin e ver o que acontece: 
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Figura 6.12: É permitido que o admin acesse o recurso 
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6.5 CARREGANDO OS USUÁRIOS PELO 
BANCO DE DADOS 


Vamos agora iniciar a transição para um modelo onde os 
usuários estejam no nosso banco de dados. Isso, claro, traz uma 
série de benefícios: 


e Os usuários serão persistentes entre desligar e ligar 
novamente a aplicação (no nosso caso isso não acontece 
pois nosso banco de dados está em memória, mas isso é 
facilmente modificável); 

e Várias instâncias diferentes do nosso programa podem 
enxergar o mesmo banco de dados e, portanto, os mesmos 
usuários; 

e É possível criar novos usuários e modificá-los, e transmitir 
essa mudança para várias instâncias diferentes do nosso 
programa. 


Para isso, vamos começar criando uma entidade que represente 
nossos usuários. Cada um deles vai contar com os seguintes 
atributos: um nome de usuário, uma senha, uma lista de papéis e 
um atributo para dizer eles estão habilitados ou não. Este último é 
utilizado para podermos ter a capacidade de "desligar" um usuário 
sem apagá-lo fisicamente do banco de dados. 


Assim sendo, nossa entidade de usuário pode ficar assim: 
package app.car.cap06. domain; 
import java.util.List; 
import javax.persistence.Column; 


import javax.persistence.ElementCollection; 
import javax.persistence.Entity; 
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import javax.persistence.GeneratedValue; 
import javax.persistence.Id; 
import lombok.Data; 


@Data 
@Entity 
public class User { 


@Id 

@GeneratedValue 

Long id; 
@Column(unique = true) 
String username; 
String password; 


Boolean enabled; 


@ElementCollection 
List<String> roles; 


O QUE É A ANOTAÇÃO @ELEMENTCOLLECTION? 


Essa anotação é utilizada para que possamos realizar o 
mapeamento de classes simples para o banco de dados. Da 


forma como está, isso vai fazer com que uma outra tabela seja 


criada, chamada user roles . Esta tabela vai conter uma 
coluna chamada user id, que vai ser mapeada para o id 
do usuário, e uma coluna chamada roles . Esta coluna vai 
conter os valores da lista. O JPA já faz esse mapeamento todo 
de forma transparente para nós. 





Vamos configurar o Spring Security para carregar esses 
usuários do banco de dados. Para fazer isso, precisamos de duas 
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queries, uma para carregar os usuarios propriamente ditos e outra 
para carregar os papéis associados a estes usuarios. Estas queries 
estarão diretamente vinculadas às tabelas que serão criadas com 
base na classe User que foi descrita anteriormente. 


A query para carregar o usuário precisa retornar o nome de 
usuário, a senha, e o atributo que indica se está habilitado ou não. 
Além disso, essa query recebe como parâmetro o nome de usuário 
fornecido, que pode ser representado na query por um sinal de 
interrogação ( ? ). Assim, a query fica: 


select username, password, enabled from user where username=? 


Já a query que lista os papéis é ligeiramente mais complexa, 
pois vai utilizar a tabela que foi gerada com base na anotação 
@ElementCollection . Esta query precisa retornar o nome de 
usuário e os papéis (ou seja, esta query pode retornar várias linhas 
para um único usuário). Para fazer isso, vamos precisar de ambas 
as tabelas criadas ( user e user roles ) e correlacioná-las 
utilizando o campo id da tabela user e user id da tabela 
user roles . Esta query também recebe como parâmetro o 


username . 


Com tudo isso, vamos utilizar a query assim: 


select u.username, r.roles from user roles r, user u where r.user 
_id = u.id and u.username=? 


Com as queries já criadas, vamos modificar a classe 
SecurityConfig para que ela possa realizar a carga dos usuários 
a partir do banco. Para isso, em primeiro lugar vamos injetar um 
datasource na classe SecurityConfig . Este datasource é 
uma abstração para representar uma fonte de dados, ou seja, um 
banco de dados: 
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import javax.sql.DataSource; 
import org.springframework.beans.factory.annotation.Autowired; 


//Restante do código omitido 


public class SecurityConfig extends WebSecurityConfigurerAdapter 


{ 


@Autowired 
DataSource dataSource; 


//Restante do código omitido 


Vamos também começar a cuidar de um aspecto muito 
importante da segurança da nossa aplicação: o armazenamento de 
senhas. Para toda aplicação que armazena senhas de qualquer tipo, 
uma regra muito importante é armazená-las de forma que, caso o 
banco de dados seja comprometido, não seja possível (ou seja 
muito difícil) reverter o que está armazenado de volta para as 
senhas verdadeiras. Como via de regra, armazenamos hashes das 
senhas em vez da senha original. Um hash é um código gerado a 
partir da senha original de forma que uma mesma senha gere uma 
saída previsível, mas que o processo seja irreversível. Para 
determinar se uma senha é equivalente ao hash dela, o sistema 
tira o hash da senha fornecida pelo cliente e verifica se é 
equivalente ao hash armazenado. Se for igual, o processo de 
autenticação é feito com sucesso. 
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SE O HASH SEMPRE GERA A MESMA SAIDA, NAO BASTA TER UM 
DICIONARIO DE SAIDAS PARA REVERTER O PROCESSO? 


É válido pensar que, se os usuários quase sempre usarem a 


senha 123456 , por exemplo, teremos armazenado no banco 
de dados vários hashes iguais e, desta forma, saber que a 
senha do usuário é 123456 , mesmo enxergando apenas o 
hash . Com base nisso, foi criado o conceito de salt , que é 
um dado conhecido pelo gerador de hashes e que é anexado 
na senha que vai passar pelo processo. Desta forma, o salt 
faz com que o hash da mesma senha seja diferente para 
diferentes usuários, o que dificulta bastante o processo de 
adivinhar qual a senha de um determinado usuário. 


O sistema utilizado pelo Spring Security por padrão (que 
vamos ver a seguir) utiliza o salt nativamente, de forma 
que não vamos precisar nos preocupar com esse aspecto da 
segurança. 





Para utilizar este sistema, o Spring Security nos fornece uma 
interface que é a  PasswordEncoder . Basta termos uma 
implementação desta interface disponível no contexto do Spring 
que ele já a usa automaticamente em diversos contextos, mas não 
em todos. Assim, vamos criar um método que insere a 
implementação BCryptPasswordEncoder no contexto do Spring 
- o que é feito criando-se um método público na classe 
SecurityConfig anotado com @Bean : 


import org.springframework.security.crypto.bcrypt.BCryptPasswordE 
ncoder; 
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import org.springframework.security.crypto.password.PasswordEncod 
er; 
import org.springframework.context.annotation.Bean; 


public class SecurityConfig extends WebSecurityConfigurerAdapter 


{ 


@Bean 
public PasswordEncoder passwordEncoder() { 
return new BCryptPasswordEncoder (); 


} 


Finalmente, estamos prontos para reconfigurar o sistema de 
autenticação. Para isso, vamos deixar comentado o sistema que 
tínhamos criado anteriormente, com os usuários em memória: 


@Override 
public void configure(AuthenticationManagerBuilder auth) 
throws Exception { 


f* 
String password = "{noop}password"; 


User.UserBuilder driver = User.builder() 
.username("driver") 
. password(password) 
.roles("DRIVER"); 


User .UserBuilder passenger = User.builder() 
.username("passenger") 
.password( password) 
. roles ("PASSENGER"); 


User.UserBuilder admin = User.builder() 
.username( "admin" ) 
. password(password) 
.roles("ADMIN"); 


auth. inMemoryAuthentication() 
.withUser (driver) 
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.withUser (passenger) 


.withUser (admin) 
r 
RA 
3 
Vamos colocar as queries que tínhamos criado anteriormente 
em Strings: 
String queryUsers = "select username, password, enabled from user 
where username=?"; 
String queryRoles = "select u.username, r.roles from user roles r 


, User u where r.user id = u.id and u.username=?"; 


E agora, vamos modificar o objeto auth para ir buscar os 
dados no banco de dados, utilizando o método 
jdbcAuthentication . Para que ele saiba em qual banco de dados 
buscar as informações, vamos injetar a instância do datasource 
utilizando o método dataSource() : 


auth. jdbcAuthentication().dataSource(dataSource); 


Vamos fornecer uma instância do PasswordEncoder para 
que não haja problemas com a autenticação: 
auth. jdbcAuthentication() 


.dataSource(dataSource) 
. passwordEncoder (passwordEncoder ()); 


Por último, vamos fornecer as queries para recuperar os 
usuários e os papéis através dos métodos 
usersByUsernameQuery e authoritiesByUsernameQuery , 
respectivamente: 
auth. jdbcAuthentication() 
.dataSource(dataSource) 
. passwordEncoder (passwordEncoder()) 


. usersByUsernameQuery(queryUsers) 
.authoritiesByUsernameQuery(queryRoles); 
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Para conferéncia, a classe completa ficou assim: 
package app.car.cap06.config; 


import javax.sql.DataSource; 

import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.context.annotation.Bean; 

import org.springframework.context.annotation.Configuration; 
import org.springframework.security.config.annotation.authenticat 
ion. builders.AuthenticationManagerBuilder; 

import org.springframework.security.config.annotation.method.conf 
iguration.EnableGlobalMethodSecurity; 

import org.springframework.security.config.annotation.web. builder 
s.HttpSecurity; 

import org.springframework.security.config.annotation.web.configu 
ration.EnablewebSecurity; 

import org.springframework.security.config.annotation.web.configu 
ration.WebSecurityConfigurerAdapter ; 

import org.springframework.security.config.http.SessionCreationPo 
licy; 

import org.springframework.security.crypto.bcrypt.BCryptPasswordE 
ncoder; 

import org.springframework.security.crypto.password.PasswordEncod 
er; 


@Configuration 

@EnableWebSecurity 

@EnableGlobalMethodSecurity(jsr250Enabled = true) 

public class SecurityConfig extends WebSecurityConfigurerAdapter 


{ 


@Autowired 
DataSource dataSource; 


@Override 
protected void configure(HttpSecurity http) throws Exception { 
http.csrf().disable(); 


http.sessionManagement ( ) 
.sessionCreationPolicy(SessionCreationPolicy.STATELESS) ; 


http 


.authorizeRequests() 
.anyRequest() 
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.authenticated() 


.«and() 
-httpBasic(); 
} 
@Override 


public void configure(AuthenticationManagerBuilder auth) 
throws Exception { 


Fda 
String password = "{noop}password"; 


User.UserBuilder driver = User.builder() 
.username("driver") 
. password (password) 
.roles("DRIVER"); 


User.UserBuilder passenger = User.builder() 
.username("passenger") 
.password(password) 

.roles("PASSENGER"); 


User .UserBuilder admin = User.builder() 
. username ("admin") 
. password(password) 
.roles("ADMIN"); 


auth. inMemoryAuthentication() 
.withUser (driver) 


.withUser (passenger ) 
.withUser (admin) 
r 
ay. 
String queryUsers = "select username, password, enabled fro 
m user where username=?"; 
String queryRoles = "select u.username, r.roles from user_r 


oles r, user u where r.user_id = u.id and u.username=?",; 


auth. jdbcAuthentication() 
.dataSource(dataSource) 
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. passwordEncoder (passwordEncoder()) 
.UsersByUsernameQuery (queryUsers) 
.authoritiesByUsernameQuery(queryRoles); 


@Bean 
public PasswordEncoder passwordEncoder() { 
return new BCryptPasswordEncoder(); 


Para testar, vamos criar um modo de salvar nosso usuario no 
banco de dados e nos autenticar com ele. Para isso, primeiro 
vamos criar um repositório de usuários, da mesma forma como 
criamos os das outras entidades do sistema: 


package app.car.cap06.domain; 
import org.springframework.data.jpa.repository.JpaRepository; 


public interface UserRepository extends JpaRepository<User, Long> 


{ 
} 


Agora, vamos criar uma nova configuração para que nossa 
aplicação possa recuperar os objetos adequados e realizar a 
persistência de um User no banco de dados. Vamos criar uma 
nova classe chamada  LoadUserConfig e anotá-la com 
@Configuration : 


package app.car.cap06.config; 
import org.springframework.context.annotation.Configuration; 


@Configuration 
public class LoadUserConfig { 


A seguir, vamos injetar tanto 0 PasswordEncoder quanto o 


180 6.5 CARREGANDO OS USUARIOS PELO BANCO DE DADOS 


UserRepository , através da anotação @Autowired : 


import app.car.cap06.domain.UserRepository; 

import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework.security.crypto.password.PasswordEncod 
er; 


// Restante dos imports omitidos 


@Configuration 
public class LoadUserConfig { 


@Autowired 
PasswordEncoder passwordEncoder; 


@Autowired 
UserRepository userRepository; 


Vamos agora criar um método que sera responsavel por 
executar a criação do usuário. Podemos sinalizar para o Spring que 
esse método deverá ser invocado após a injeção dos campos, 
utilizando a anotação @PostConstruct : 


import javax.annotation.PostConstruct; 
public class LoadUserConfig { 


@PostConstruct 
public void init() { 


} 


Finalmente, vamos codificar o método init para que um 
usuário seja inserido no repositório e possamos fazer nossos testes. 
Para manter um contexto adequado com o que estávamos 
trabalhando antes, este usuário vai ser o admin , com a senha 

password , um único papel ROLE ADMIN e, obviamente, 
habilitado. A senha vai precisar estar codificada, conforme 
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explanado anteriormente. Assim, vamos utilizar o método 


encode antes de passar a senha para o usuário. A criação toda fica 


desta forma: 


import java. 


util.Arrays; 


@PostConstruct 
public void init() { 
User admin = new User(); 


admin. 
admin. 
admin. 
admin. 


setPassword(passwordEncoder.encode("password")); 
setRoles(Arrays.asList ("ROLE ADMIN")); 
setUsername("admin"); 

setEnabled(true); 


userRepository.save(admin) ; 


Desta forma, assim que iniciarmos o sistema, vamos ter um 


usuario admin criado no banco de dados. 


Vamos testar novamente usando o Postman. Basta deixar o 


usuário criado como admin easenhacomo password , e realizar 


a requisição para criação do passageiro: 
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Figura 6.13: Passageiro criado com o usuário admin 


6.6 ATUALIZAÇÃO DOS TESTES 
INTEGRADOS 


Como atualizamos o nosso sistema para utilizar HTTPS e 
autenticação, os testes com o REST Assured precisam refletir essas 
novas configurações. Primeiro, vamos alterar os testes para que o 
REST Assured utilize HTTPS em vez do padrão HTTP. Isso pode 
ser feito utilizando o atributo estático baseURI da classe, que 
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define para o REST Assured qual será a URI base de todas as 
requests efetuadas por ele. Se esse atributo for configurado para 
um endereço com HTTPS, ele sempre utilizará HTTPS nas 
requests feitas. 


Tomando como base a classe PassengerAPITestIT , vamos 
modificar o método setup() para que utilize esse atributo. 
Observe que, uma vez que o utilizamos, temos que especificar a 
porta utilizada - desta forma, dispensando o uso do atributo port 
usado anteriormente: 


@BeforeEach 
public void setup() { 
RestAssured.baseURI = "https://localhost:" + port; 


} 
Ao executar o código, podemos nos deparar com uma 
mensagem semelhante a seguinte: 
javax.net.ssl.SSLHandshakeException: PKIX path 
building failed: 


sun.security.provider.certpath.SunCertPathBuilderExcept 
ion: unable to find valid certification path to 
requested target . Isso acontece por causa do certificado que é 
autoassinado (semelhante ao problema que ocorria com o 
Postman). Para contornar este problema, utilizamos o método 
useRelaxedHTTPSValidation() do REST Assured: 

@BeforeEach 

public void setup() { 


RestAssured.baseURI = "https://localhost:" + port; 
RestAssured.useRelaxedHTTPSValidation(); 


Quando executamos novamente o teste, temos o seguinte erro: 


java. lang.AssertionError: 1 expectation failed. 
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Expected status code <200> but was <401>. 


Como vimos anteriormente, esse código de status indica que 
não estamos utilizando autorização. Podemos passar a utilizá-la 
através do atributo estático authentication do REST Assured. 
Para indicar que é um sistema de autenticação Basic, vamos 
utilizar o método estático basic() para informar as credenciais 
do nosso usuário admin : 


import static io.restassured.RestAssured.basic; 


@BeforeEach 

public void setup() { 
RestAssured.baseURI = "https://localhost:" + port; 
RestAssured.useRelaxedHTTPSValidation(); 
RestAssured.authentication = basic("admin", "password"); 


Agora, os testes vão passar. Vamos replicar a mesma alteração 
para a classe TravelRequestAPITestIT , para que os testes 
passem. 


ALERTA DE BOAS PRÁTICAS 


Caso você tenha muitos testes, pode ser interessante utilizar 
uma estratégia de separar essas configurações em uma classe à 
parte e apenas invocar a chamada no teste. No caso dos 
exemplos deste livro, não considerei proveitoso fazer isso por 
serem apenas dois. No entanto, se você tiver curiosidade a 
respeito da melhor forma de como fazer isso, não se esqueça 
de conferir o repositório oficial de códigos deste livro em 


https://github.com/alesaudate/rest-v2. 
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Conclusao 


Até aqui, vimos alguns dos conceitos mais básicos de segurança 
de APIs. Conhecemos o mecanismo de funcionamento de 
certificados, HTTPS e autenticação básica para usuários dentro do 
sistema. Do ponto de vista de serviços, pode-se dizer que os nossos 
estão concluídos. 


Mas criar e disponibilizar APIs são mais do que isso. Trata-se 
de criar serviços que apresentam boa documentação e, de certa 
forma, “chamam” novos usuários, tamanha é a usabilidade dos 
serviços. 


Na próxima parte, vamos conhecer técnicas para expandir a 
usabilidade dos serviços que implementamos, criando esse convite 
para seus usuários. 
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APIs 


CaríTULO 7 


APIS 


"Todos os homens têm, por natureza, desejo de conhecer” - 
Aristóteles 


A partir deste capítulo, quero convidar você a vislumbrar um 
novo passo na evolução dos nossos serviços. Neste passo, vamos 
aprender a converter os serviços que estamos construindo em 
REST para algo que seja verdadeiramente fácil de se utilizar, e que 
possa realmente instigar os usuários a quererem utilizar as APIs. 


Vamos dissecar o assunto a partir da definição do que é uma 
API. Esta é a sigla para Application Programming Interface, ou 
Interface de programação de aplicações. Trata-se de uma forma de 
comunicação com o software que procura abstrair totalmente os 
detalhes da implementação subjacente - ou ao menos tanto quanto 
for possível. 


Para entender melhor esse conceito, vamos detalhar o que é 
uma interface. Intuitivamente, você conhece interfaces, pois você já 
teve que lidar com algumas delas. Quando você ligou seu 
computador, em algum momento você viu a interface gráfica do 
seu Sistema Operacional (seja Windows, Linux, Mac, ou qualquer 
outro). Repare no termo: interface gráfica. Isso significa que o seu 
Sistema Operacional oferece uma abstração de natureza gráfica 
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para que vocé nao tenha que lidar com detalhes inerentes a 
implementação. Em outras palavras, o computador oferece 
facilidades que estão disponíveis graficamente para que você não 
tenha que acessar a implementação interna do Sistema e mexer 
diretamente no código interno dele. 


Além desse exemplo, vale observar um que está mais próximo 
da realidade dos programadores Java, isto é, as próprias interfaces 
que a linguagem disponibiliza para nós. Quando declaramos uma 
interface em Java, ela não tem implementação alguma (pelo 
menos, até o Java 8 não tinha). Isso forçava o programador a 
exercer uma técnica chamada desenvolvimento orientado a 
interface, ou seja, declarar métodos pensando na usabilidade em 
primeiro lugar, e abstraindo o máximo possível quaisquer detalhes 
sobre a implementação desses métodos. 


Entendemos que uma API é uma interface para o 
programador, e uma interface é uma forma de se interagir com o 
sistema sem conhecer seu funcionamento interno. Mas qual a 
importância dessas APIs? 


Em primeiro lugar, temos que entender que o propósito de 
uma API é tornar o uso do sistema fácil e conveniente para que 
programadores não familiarizados com ele possam criar código 
por meio dele rapidamente. Esta tem sido a base de muitos 
sistemas que conhecemos hoje, e realmente é bem difícil 
estabelecer um roadmap de sucesso de um novo sistema na 
internet sem uma API disponível. Quando nós temos uma API 
para o público utilizar, expandimos o público-alvo do nosso 
sistema e este passa a contemplar também desenvolvedores que 
queiram integrar suas funcionalidades em seus próprios sistemas. 
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Um grande exemplo desse cenário são as redes sociais, como o 
Facebook. Uma vez que o Facebook oferece algumas de suas 
funcionalidades expostas por APIs, ele mesmo expande seu 
público-alvo para desenvolvedores que queiram construir 
funcionalidades utilizando o Facebook. Um desenvolvedor pode 
oferecer em seu site login via Facebook, ou pode construir um 
chatbot para o próprio Facebook, ou pode ainda detectar algumas 
das preferências do usuário. Enfim, existem várias possibilidades a 
serem construídas a partir do uso de APIs - e isso não diminui a 
popularidade do próprio Facebook, mas aumenta. Isso porque 
mais e mais sistemas passam a ser, na verdade, dependentes do 
Facebook para que estas funcionalidades permaneçam no ar. 


Para se implementar uma boa API é fundamental 
compreender que é necessário que esta API seja tão próxima 
quanto possível de ser autoexplicativa e também ter uma boa 
documentação. Isso significa seguir algumas regras, tais como: 


e Ter URLs significativas 

e Utilizar os códigos HTTP corretos 

e Em caso de erros, é importante fornecer mensagens de erro 
detalhando os erros 

e Caso seja uma API pública, fazer com que esta seja 
retrocompatível 

e Ter uma boa documentação 


7.1 COMO CRIAR URLS SIGNIFICATIVAS 


Como vimos até aqui, cada URL que criamos estava 
relacionada a conceitos simples, tais como /drivers para 
motoristas, /passengers para passageiros, e assim por diante. 
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Mas o que fazer em caso de conceitos aparentemente relacionados, 
tais como as viagens ja relacionadas por um determinado 
motorista, ou passageiro? 


Geralmente, nesses casos quem desenvolve costuma recorrer a 
hierarquização de URLs. Por exemplo, para listar as viagens já 
percorridas por um determinado motorista (digamos, identificado 
por 1 ), cria-se uma URL /drivers/1/travels . Apesar de esse 
desenvolvimento parecer inofensivo à primeira vista, esta ideia 
pode levar à explosão de novas URLs para lidar com estes 
conceitos ou correlatos e, em casos mais extremos, torna muito 
difícil ou impossível a manutenção da API. 


O correto seria tratar de cada URL como a representação de 
um conjunto - no sentido mais próximo que isso pode estar do 
conceito matemático. 


Explico: ao desenvolver a URL /drivers , criamos a 
identificação de um conjunto onde estão contidos diversos 
motoristas. Podemos selecionar alguns deles de acordo com um 
filtro aplicado (por exemplo: /drivers?firstName=Alexandre ), 
ou podemos selecionar um motorista específico de acordo com um 
subconjunto da URL - /drivers/1 . Ao optar por esta última, no 
entanto, note que criamos um subconjunto do conjunto inicial, e 
não apenas filtramos. Este subconjunto em particular contém 
apenas um motorista, 


Nesta linha de raciocínio, já começa a parecer mais difícil 
“encaixar” o conceito de viagens. Afinal de contas, precisamos ter a 
noção de pertencimento: o motorista 1 faz parte do conjunto de 
motoristas, pois ele é um motorista. Já as viagens que ele fez não 
são motoristas, são viagens. São conceitos relacionados, mas não 
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têm uma relação de pertencimento. 


Observe que aqui também se encaixam alguns conceitos 
clássicos de Orientação a Objetos: alguns relacionamentos podem 
ser do tipo TEM-UM (por exemplo: um cachorro TEM UMA 
coleira) e outros relacionamentos podem ser do tipo É-UM (um 
cachorro É UM animal). 


A partir deste conceito, percebe-se por que a URL 
/drivers/1/travels está conceitualmente errada. Para estar 
correta, seria necessário que as viagens fossem motoristas. Mas o 
relacionamento entre eles é do tipo TEM-UM e não É-UM. Daí 
entra a necessidade de se utilizar HATEOAS. Quando conceitos 
estão relacionados desta forma, faz mais sentido. 


Além disso, também vale ressaltar que, como as URLs são uma 
representação de conjuntos, não faz sentido algum nomeá-las 
utilizando verbos. Em geral, utilizamos apenas substantivos e, em 
alguns casos mais complexos, adjetivos (como foi o caso da API 
que criamos no capítulo 4 /travelRequests/nearby ). Observe 
que, por mais que levemos em consideração a noção de conjuntos 
matemáticos equivalentes a cada segmento de URL, o segmento 

/nearby é um adjetivo e, portanto, está filtrando 

travelRequests . Em outras palavras, o conjunto representado 

por /travelRequests contém o subconjunto representado por 
/nearby . 


Quando você tiver dúvidas de que tipo de mecanismo utilizar 
para filtragens (via segmento de URL ou query params ), prefira 
query params por ser um mecanismo mais extensível. Utilize 
segmentos de URL apenas quando não fizer sentido qualquer 
espécie de filtragem extra dentro do conjunto em questão. 
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7.2 UTILIZAR OS CODIGOS HTTP CORRETOS 


Conhecemos ao longo do livro alguns dos cédigos HTTP mais 
usados. Veremos agora um detalhamento um pouco maior destes 
códigos para entender quando usar cada um deles. Primeiro, 
vamos entender as "familias" dos códigos HTTP para entender a 
classificação deles: 


Ixx 


Códigos que iniciam com 1 são apenas informativos e não 
costumam ser de grande utilidade em contextos HTTP/REST. 


2xx 
São os códigos de sucesso. Os mais usados são: 


e 200 OK: é uma resposta "genérica" de sucesso, e indica 
que no resultado da requisição deve haver um corpo. 

e 201 Created : indica que o recurso foi criado. Deve 
incluir um cabeçalho Location indicando a URL onde o 
recurso está disponível. 

e 202 Accepted : significa que a requisição foi recebida, 
mas será processada de forma assincrona. 

e 204 No Content : a requisição foi processada, mas não ha 
conteúdo algum para ser retornado no corpo. 


3xx 


São códigos de redirecionamento, ou seja, a resposta depende 
de outras requisições. Existe uma grande fonte de confusão nesta 
família (que família não tem confusões, não é mesmo?), que é o 
fato de que muitos browsers populares implementaram alguns 
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códigos com o comportamento de outros. Devido a este fato, o 
comportamento de alguns códigos passa a ser muito semelhante, 
então vou procurar agrupar aqueles que têm comportamento 
semelhante: 


e 301 Moved Permanently : indica que o recurso presente 
nesta URL mudou-se permanentemente e novas 
requisições devem ser feitas para o novo endereço. 

e 302 Found e 303 See Other : significa que o resultado 
do processamento realizado por esta URL está presente em 
outro endereço. Isso quer dizer que, caso o usuário tenha 
feito uma requisição com POST ou PUT, por exemplo, o 
resultado vai estar em outra URL e deve ser obtido usando 
GET. 

e 304 Not Modified : não é de redirecionamento. É usado 
em cenários onde alguma técnica de cache foi usada, 
indicando que o recurso não foi modificado no servidor e 
que o usuário pode reaproveitar a mesma versão que ele 
tem salva localmente. 

e 307 Temporary Redirect : semelhante ao 302 e 303 
(veja parágrafo a seguir para mais detalhes). 


A confusão que envolve os códigos 302, 303 e 307 se dá 
por uma implementação errônea dos fabricantes de browsers e a 
especificação. Essa falha de entendimento já foi corrigida e, hoje, o 
código 302 não deve mais ser usado. Em substituição, utilize o 

301 caso o redirecionamento seja permanente; 303 , caso o 
redirecionamento seja temporário e a nova requisição precise ser 
feita com o método GET ;e 307 , caso o mesmo método utilizado 
para realizar a requisição no primeiro endereço precise ser usado 
para realizar a requisição no novo endereço (i.e. se eu utilizei 
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POST para realizar uma requisição em /travelRequests e esta 
requisição retornou o código 307 , então eu devo realizar uma 
nova requisição utilizando o método POST no endereço 
apontado). 


4xx 


São códigos de erros que se originaram a partir de alguma ação 
tomada por parte do cliente. Geralmente, podem ser corrigidos se 
o cliente mudar alguma informação na requisição. Incluem erros 
na formatação dos dados enviados, autenticação/autorização, 
conflito com os dados já contidos no servidor etc. 


e 400 Bad Request : é uma resposta genérica de erro 
causado por uma ação do cliente. Pode ser utilizada para 
indicar que um tipo de dado não está bem formatado ou 
não é aceito, por exemplo: enviar letras em um campo de 
CEP. 

e 401 Unauthorized : indica que a autenticação é 
requerida, mas os dados nao foram encontrados ou 
falharam (i.e. senha errada, por exemplo). Curiosamente, o 
texto de status deste código significa "Não Autorizado” 
(quando, na opinião deste autor, deveria ser "Não 
Autenticado”). 

e 403 Forbidden : indica que a autorização necessária não 
foi concedida para acessar a URL em questão. Nesse caso, a 
própria especificação alerta que, caso os dados de 
autenticação não sejam modificados, o pedido não deve ser 
reenviado. 

e 404 Not Found : é um dos códigos de erro mais usados de 
todos. Indica que o recurso que deveria estar presente em 
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uma determinada URL não está. 

e 409 Conflict : é utilizado para casos de conflito entre 
recursos. Nasceu com o propósito de ser utilizado onde 
mecanismos de lock otimista estão presentes; no entanto, 
por significar que existe algo em conflito no servidor, teve 
seu uso expandido para outros casos, como quando o 
próprio cliente fornece o ID do recurso a ser criado para o 
servidor e o referido ID já está em uso. 


5xx 


São códigos de erros que se originaram a partir de algo errado 
que aconteceu no lado do servidor. Estes erros geralmente não 
podem ser corrigidos a partir de correções na requisição e apenas 
os mantenedores do serviço podem corrigir as falhas. 


e 500 Internal Server Error : é uma resposta genérica 
de erro interno do servidor. Por si só, indica apenas alguma 
falha não tratada no servidor. Geralmente, o código que 
escrevemos no Spring Boot já traduz a resposta para esse 
código automaticamente caso qualquer exceção seja 
propagada. 

e 503 Service Unavailable : é uma resposta que indica 
que o servidor não está disponível. Esse erro geralmente é 
dado quando a requisição HTTP que fizemos é 
redirecionada internamente para que outro serviço atenda 
à requisição e este serviço não está disponível. 


Vale lembrar que essa lista não está completa (longe disso), por 
dois motivos principais: o primeiro é que nem todos os códigos 
definidos pela especificação HTTP são utilizáveis em REST. Temos 
até o caso de um código que é uma pegadinha de primeiro de abril 
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e acabou entrando para a lista oficial de codigos de status (se vocé 
tiver curiosidade, é o código 418 I'm a teapot , que indica que 
o servidor nao pode preparar café por ser um bule de cha). O 
segundo motivo é que muitos códigos têm contextos muito 
específicos e acabam sendo muito pouco usados (um exemplo é o 
código 450 Blocked by Windows Parental Controls , o que 
significa que a requisição foi bloqueada pelo controle parental do 
Windows). 


7.3 FORNECER MENSAGENS DE ERRO 
SIGNIFICATIVAS 


Uma questão importante a ser trabalhada quando falamos de 
APIs é prover uma boa experiência relacionada aos casos de erro. 
Esses erros devem ser claros, de forma a orientar da melhor forma 
possível o cliente a tratá-los (caso sejam erros da família 4xx ) ou 
como obter algum feedback (caso sejam erros da família 5xx ). 


Vamos ver como realizar este tipo de tratamento a partir da 
validação de dados, utilizando a API de solicitação de viagens 
como exemplo. Vamos revisar a classe TravelRequestInput : 


@Data 
public class TravelRequestInput { 


Long passengerId; 
String origin; 
String destination; 


Essa classe fica no pacote que delimita entradas das APIs do 


sistema, então é importante que ela tenha algumas validações de 
informações para minimizar a possibilidade de entrada de dados 
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que provoquem erros no sistema. Vamos examinar uma possivel 
entrada de erros: o método map da classe 
TravelRequestMapper . Esse método recebe como parâmetro um 

TravelRequestInput e faz a transformação deste para um 
TravelRequest , que é um objeto de domínio. Vamos revisar o 
código: 


public TravelRequest map(TravelRequestInput input) { 


Passenger passenger = passengerRepository.findById(input.getPa 
ssengerId()) 
.orElseThrow(() -> new ResponseStatusException(HttpStatus.N 
OT. FOUND)); 


TravelRequest travelRequest = new TravelRequest(); 
travelRequest.setOrigin(input.getOrigin()); 
travelRequest.setDestination(input.getDestination()); 
travelRequest.setPassenger (passenger); 


return travelRequest; 


A primeira coisa que esse método faz é localizar os dados do 
passageiro a partir do passengerId passado como parâmetro. 
Mas e se esse atributo não for fornecido na requisição? 


Como fizemos antes, vamos utilizar o Postman para verificar 
essa situação realizando um POST na URL /travelRequests 
Vamos enviar os seguintes dados: 

{ 


"origin": "string", 
"destination": "string" 


Observe que o passengerId foi omitido. Da forma como 
esta, recebemos uma resposta semelhante a seguinte: 


{ 


198 7.3 FORNECER MENSAGENS DE ERRO SIGNIFICATIVAS 


"timestamp": "2020-02-16T18:46:58.407+0000", 

"status": 500, 

"error": "Internal Server Error", 

"message": "The given id must not be null!; nested exception 
is java.lang.IllegalArgumentException: The given id must not be n 
ulli", 

"trace": "org.springframework.dao.InvalidDataAccessApiUsageEx 
ception: The given id must not be null!; nested exception is java 
.lang.IllegalArgumentException: The given id must not be null!\n\ 
tat org.springframework.orm. jpa.EntityManagerFactoryUtils.convert 
JpaAccessExceptionIfPossible(EntityManagerFactoryUtils.java:374)\ 
n\tat org.springframework.orm.jpa.vendor.HibernateJpaDialect.tran 
slateExceptionIfPossible(HibernateJpaDialect.java:256)\n\tat org. 
springframework.orm.jpa.AbstractEntityManagerFactoryBean.translat 
eExceptionIfPossible(AbstractEntityManagerFactoryBean. java:528)\n 
\tat org.springframework.dao.support.ChainedPersistenceExceptionT 
ranslator.translateExceptionIfPossible(ChainedPersistenceExceptio 
nTranslator.java:61)\n\tat org.springframework.dao.support.DataAc 
cessUtils.translateIfNecessary(DataAccessUtils.java:242)\n\tat or 
g.springframework.dao.support.PersistenceExceptionTranslationInte 
receptor. invoke(PersistenceExceptionTranslationInterceptor.java:15 
3)\n\tat org.springframework.aop.framework.ReflectiveMethodInvoca 
tion.proceed(ReflectiveMethodInvocation.java:186)\n\tat org.spri 
ngframework.aop.framework.ReflectiveMethodInvocation.proceed(Refl 
ectiveMethodInvocation. java:186)\n\tat org.springframework.aop.in 
terceptor.ExposeInvocationInterceptor. invoke(ExposeInvocationInte 
rceptor.java:93)\n\tat org.springframework.aop. framework. Reflecti 
veMethodInvocation.proceed(ReflectiveMethodInvocation.java:186)" 

"path": "/travelRequests" 


Recebemos um erro HT'TP 500. Como vimos acima, esta é uma 
exceção não tratada do lado do servidor de fato, mas que teve 
origem na requisição que foi enviada de forma incorreta. Ou seja, o 
retorno correto deveria ser um HTTP 400. Vamos iniciar o 
tratamento para isso. 


O primeiro passo é introduzir a devida validação nos campos 
para que o sistema do Spring Boot não deixe a requisição 
prosseguir no código caso alguma informação esteja incorreta (no 
nosso caso, o passengerId faltando). Isso pode ser feito através 
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do uso das anotações referentes à JSR 380, também conhecida 
como Bean Validation 2.0. Esta especificação inclui anotações 
para validação de vários aspectos do sistema (inclusive dados 
válidos apenas no Brasil, como CPF e CNPJ), e o Spring Boot já se 
integra automaticamente a ela. 


Vamos utilizar a anotação @NotNull para declarar que o 
campo passengerId não pode ser nulo - assim sendo, as 
requisições que vierem sem esse campo deverão ser recusadas: 


import javax.validation.constraints.NotNull; 


@Data 
public class TravelRequestInput { 


@NotNull 

Long passengerId; 
String origin; 
String destination; 


Agora, no ponto da chamada que declara o método POST, 
vamos incluir a anotação (valid , que indica que o Bean 
Validation deve ser utilizado sobre este parâmetro: 


import javax.validation.Valid; 
//Restante do código omitido 


@PostMapping 
public EntityModel<TravelRequestOutput> makeTravelRequest ( 
@RequestBody @Valid TravelRequestInput travelRequestInput) 


{ 


TravelRequest request = travelService.saveTravelRequest (mapper 
.map(travelRequestInput)); 

TravelRequestOutput output = mapper.map(request); 

return mapper.buildOutputModel(request, output); 
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Se realizarmos a requisição do Postman agora, já vamos ter um 


resultado bem diferente: 


"timestamp": "2020-02-16T19:03:14.142+0000", 
"status": 400, 


"error": 


"Bad Request", 


"errors": [ 


{ 


} 
l; 


"codes": [ 
"NotNull.travelRequestInput.passengerId", 
"NotNull.passengerId", 
"NotNull.java.lang.Long", 

"NotNull" 

1, 

"arguments": [ 
{ 

"codes": [ 
"travelRequestInput.passengerId", 
"passengerId" 

Is 

"arguments": null, 

"defaultMessage": "passengerId", 

"code": "passengerId" 

; 

L 

"defaultMessage": "must not be null", 

"objectName": "travelRequestInput", 

"field": "passengerId", 

"rejectedValue": null, 

"bindingFailure": false, 

"code": "NotNull" 


"message": "Validation failed for object='travelRequestInput ' 
Error counts 1º, 


"trace": 


"org.springframework.web.bind.MethodArgumentNotValid 


Exception: Validation failed for argument [0] in public org.sprin 
gframework.hateoas.EntityModel<app.car.cap07.interfaces.incoming. 
output.TravelRequestOutput> app.car.cap07.interfaces.incoming.Tra 
velRequestAPI.makeTravelRequest (app.car.cap07. interfaces. incoming 
. input.TravelRequestInput): [Field error in object 'travelRequest 
Input' on field 'passengerId': rejected value [null]; codes [NotN 
ull.travelRequestInput.passengerId, NotNull. passengerId, NotNull.ja 
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va.lang.Long,NotNull]; arguments [org.springframework.context.sup 
port .DefaultMessageSourceResolvable: codes [travelRequestInput.pa 
ssengerId, passengerId]; arguments []; default message [passengerI 
dj]; default message [must not be null]] \n\tat org.springframewo 
rk.web. servlet .mvc.method.annotation.RequestResponseBodyMethodPro 
cessor.resolveArgument (RequestResponseBodyMethodProcessor. java:13 
9)\n\tat org.springframework.web.method.support.HandlerMethodArgu 
mentResolverComposite.resolveArgument (HandlerMethodArgumentResolv 
erComposite. java:121)\n\tat org.springframework.web.method. suppor 
t.InvocableHandlerMethod.getMethodArgumentValues(InvocableHandler 
Method. java:167)\n", 
"path": "/travelRequests" 


} 


Já está muito melhor: o código HTTP foi 400 (que era nossa 
intenção), e existe uma mensagem indicando que houve algo de 
errado relacionado ao campo passengerId . Mas ainda não está 
amigável o suficiente e, pior de tudo, não seria possível utilizar a 
mesma estrutura de erro para outros cenários. 


Assim sendo, precisamos criar uma estrutura onde seja 
possível definir um payload que seja extensível para todos os 
cenários de falha nossos. Para o nosso caso, em específico, um 
JSON simples nos atenderia muito bem. Por exemplo: 


{ 
"errors": [ 
{ 
"message":"0 campo passengerId não pode ser nulo" 
J 
] 
} 


Perceba que se trata de uma estrutura externa (que é onde o 
campo errors esta) e uma estrutura interna (que abriga o campo 
message ). Vamos então criar um pacote para armazena-las (que 
vamos chamar de 


app.car.cap07.interfaces.incoming.errorhandling ) e duas 
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classes que representam essas duas estruturas, comecando pela 
mais interna. Esta classe contém dados especificos sobre cada erro, 
então vamos chamá-la de ErrorData : 


package app.car.cap07.interfaces.incoming.errorhandling; 


import lombok.AllArgsConstructor; 
import lombok.Data; 


@A11ArgsConstructor 
@Data 


public class ErrorData { 


private final String message; 


Em seguida, vamos criar a segunda classe, mais externa, que 
conterá uma lista de objetos ErrorData . Por ser algo mais global, 
vamos chamá-la de ErrorResponse : 


package app.car.cap07. interfaces. incoming.errorhandling; 


import lombok.AllArgsConstructor; 
import lombok.Data; 


import java.util.List; 
@A11ArgsConstructor 
@Data 


public class ErrorResponse { 


List<ErrorData> errors; 


Agora, vamos criar um sistema de captura da falha e “tradução” 
para as classes que acabamos de criar. Para isso, o Spring MVC 
disponibiliza duas anotações que têm o propósito de facilitar este 
processo. A primeira é a @RestControllerAdvice , que, como o 
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nome indica, intercepta as invocações dos métodos das APIs. A 
segunda é a @ExceptionHandler , que é parametrizada com uma 
exceção que pode eventualmente ser lançada pelo método da API 


(por exemplo, a exceção que é lançada caso a validação da entrada 
falhe). 


Quando criamos esse tratador, é necessário que seu retorno 
seja mapeável pelo Spring como retorno da API. Isso porque, uma 
vez tratada a exceção, o retorno deste método é o que será utilizado 
como retorno da API. Assim sendo, podemos criar um método 
que retorne o nosso ErrorResponse . 


O último ponto que falta definir é qual a exceção que 
precisamos tratar, tanto para parametrizar a anotação 
@ExceptionHandler quanto para parametrizar o método que 
vamos criar. Se você observar bem, verá que o nome da exceção 
que precisamos tratar já apareceu: foi ela que foi lançada assim que 
inserimos o tratamento para o campo faltando e que fez com que o 
código HTTP 400 fosse lançado. Esta exceção é a 
MethodArgumentNotValidException. 


Agora, temos o suficiente para realizar a declaração do método 
tratador: 


package app.car.cap07. interfaces. incoming.errorhandling; 


import org.springframework.web.bind.MethodArgumentNotValidExcepti 
on; 

import org.springframework.web.bind.annotation.ExceptionHandler; 
import org.springframework.web.bind.annotation.RestControllerAdvi 
ce; 


@RestControllerAdvice 
public class DefaultErrorHandler { 


204 7.3 FORNECER MENSAGENS DE ERRO SIGNIFICATIVAS 


@ExceptionHandler (MethodArgumentNotValidException.class) 
public ErrorResponse handleMethodArgumentNotValid(MethodArgum 
entNotValidException ex) { 


return null; 


Os dados de que precisamos para realizar o tratamento do erro 
estão todos contidos na exceção que, convenientemente, 
recebemos como parâmetro do método. Esta exceção contém um 
objeto do tipo BindingResult que, por sua vez, contém uma lista 
de objetos do tipo FieldError . Estes fieldErrors contêm 
uma série de dados a respeito do que originou a falha - no 
momento, vamos nos ater ao campo defaultMessage , que é a 
mensagem de erro gerada pelo sistema para indicar a falha. 


Como nós temos um construtor na classe ErrorData que 
recebe uma String como parâmetro, podemos utilizar lambdas 
para traduzir a lista de FieldError em uma lista de ErrorData: 
@ExceptionHandler (MethodArgumentNotValidException.class) 


public ErrorResponse handleMethodArgumentNotValid(MethodArgumentN 
otValidException ex) { 


List<ErrorData> messages = ex 
.getBindingResult() 
.getFieldErrors() 
.stream() 
.map(fe -> new ErrorData(fe.getDefaultMessage())) 
.collect(Collectors.toList()); 


return new ErrorResponse (messages); 


O último passo que precisamos ajustar é o código HTTP que 
será retornado quando esta exceção for tratada. Mais uma vez, 
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podemos utilizar uma anotação do próprio Spring para indicar 
qual é o código, a @ResponseStatus . Esta anotação é 
parametrizada com um objeto do tipo HttpStatus , que é um 

enum contendo todos os códigos HTTP possíveis. Como 
queremos utilizar o código HTTP 400 Bad Request , utilizamos 
então o valor HttpStatus.BAD REQUEST na parametrização desta 
anotação: 


import org.springframework.http.HttpStatus; 
import org.springframework.web.bind.annotation.ResponseStatus; 


// Restante do código omitido 


@ExceptionHandler (MethodArgumentNotValidException.class) 
@ResponseStatus(HttpStatus.BAD_ REQUEST) 

public ErrorResponse handleMethodArgumentNotValid(MethodArgumentN 
otValidException ex) { 


List<ErrorData> messages = ex 
.getBindingResult() 
.getFieldErrors() 
.stream() 
.map(fe -> new ErrorData(fe.getDefaultMessage())) 
.collect(Collectors.toList()); 


return new ErrorResponse(messages) ; 


Finalmente, podemos retestar a API. Ao realizar novamente a 
requisição com o Postman, temos o seguinte resultado: 


{ 
"errors": [ 
{ 
"message": "must not be null" 
} 
] 
} 


Esse resultado é bem semelhante ao que esperávamos 
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conseguir. A última parte que falta customizar é a mensagem, que 
não é muito significativa. Para alterá-la, basta voltarmos até a 
classe TravelRequestInput e preencher o atributo message da 
anotação @NotNull . Vamos preencher com a mensagem que 
utilizamos antes: 


@Data 
public class TravelRequestInput { 


@NotNull(message = "O campo passengerId não pode ser nulo") 
Long passengerId; 

String origin; 

String destination; 


} 
Ao retestar, obtemos o resultado desejado: 
{ 
"errors": [ 
{ 
"message": "O campo passengerId não pode ser nulo" 
} 
] 
} 


Um último teste que podemos fazer é testar o quão flexível 
nosso sistema é. Podemos adicionar validações também nos 
campos origin e destination e verificar se as mensagens 
correspondentes são lançadas sem que precisemos realizar mais 
alterações no restante do código. Sabemos que esses dois campos 
precisam estar preenchidos para que a requisição de viagem seja 
criada, então vamos utilizar a anotação @NotEmpty sobre eles 
(não esquecendo de customizar o campo message ): 


import lombok.Data; 


import javax.validation.constraints.NotEmpty; 
import javax.validation.constraints.NotNull; 
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@Data 
public class TravelRequestInput { 


@NotNull(message = "O campo passengerId não pode ser nulo") 
Long passengerId; 
(ONotEmpty (message = "O campo origin não pode estar em branco" 


String origin; 


(ONotEmpty (message = "O campo destination não pode estar em br 
anco") 

String destination; 
} 

Vamos retestar utilizando um JSON quase que inteiramente 
vazio: 
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Postman 


File Edit View Help 


ss MyWorkspace v  & Invite 





local-secure 
pos’ Create Travel Request e + o... 
+ Create Travel Request EM comments (¢ 
POST X {(host}}/travelRequests 
e (11) Body @ 
none form-data x-www-form-urlencoded ® raw binary GraphQL SON ¥ 
o] 
Body (11) Sta 400 Bad Request Time: 1278ms Size: 571B 
Pretty SON ~» > 
1 ff 
2 "errors": [ 
3 { 
4 "message": “O campo destination não pode estar em branco” 
5 h 
6 { 
7 "message": "O campo passengerId não pode ser nulo" 
8 h 
9 { 
10 "message": "O campo origin não pode estar em branco" 
11 } 
12 | 
= i 
E 4 A 7 Bootcamp Build Browse 


Figura 7.1: A request sendo completamente validada 


7.4 INTERNACIONALIZANDO AS 
MENSAGENS DE ERRO 


Uma feature também muito interessante de se ter em uma API 
REST é a internacionalização. Esse efeito é produzido quando o 
cliente informa o idioma em que deseja que as mensagens do 
sistema estejam traduzidas e as mensagens vêm naquele idioma. 
Por exemplo: digamos que eu queira que o sistema C.A.R. tenha 
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mensagens produzidas em portugués e inglés americano. Neste 


caso, o protocolo HTTP padroniza a forma como realizar esta 


solicitação para o servidor. 


Isso é feito utilizando-se o cabeçalho Accept -Language , que é 


enviado pelo cliente. Ele obedece às regras de formação da seguinte 


maneira: 


e Os valores fornecidos podem ser mais ou menos 


específicos. Por exemplo, é possível solicitar português 
(valor sendo pt ), ou português do Brasil ( pt-BR ); 

Os valores fornecidos são separados por vírgula. Por 
exemplo, para solicitar português do Brasil ou inglês, 
utilizamos pt-BR, en; 

É possível dar um peso para a ordem de preferência. O peso 
padrão é sempre 1.0 ; caso queira que um valor tenha 
menos precedência, informe um valor abaixo de 1 (porém, 
acima de 0) com o atributo q . Exemplo: pt-BR, en-US; 
q=0.8, en; q=0.6 (neste caso, a preferência será do 
português brasileiro, depois do inglês dos EUA e, por 
último, qualquer inglês disponível). 


Perceba que o parse deste cabeçalho pode ser um tanto quanto 


complicado de se fazer manualmente - primeiro, é preciso 


interpretar as ordens de preferência e, depois, filtrar a lista de 


acordo com os idiomas disponíveis no sistema. Felizmente, o 


Spring nos disponibiliza estruturas que facilitam todos estes 


passos. 
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O LOCALE 


Costumamos nos referir a estas estruturas de localização 
como locales, que podem ser mais ou menos especificos de 
acordo com a necessidade. Um locale pode fornecer 
informações sobre língua, país e até dialetos de regiões 
específicas deste país. Por exemplo, o locale do Norueguês 
padrão Nynorsk é no-NO-NY (a Noruega tem dois padrões 
de idioma, o Nynorsk e o Bokmal). O no é relativo ao 


idioma norueguês, o NO é o código da Noruega eo NY é o 


código do dialeto Nynorsk. 





O primeiro passo é criar uma pasta no sistema para que 
possamos armazenar os arquivos que vão conter as mensagens do 
sistema. Vamos chamar esta pasta de i18n (uma contração de 
internationalization, internacionalização): 


src 
main 
” BEresources 
i18n 
=) Resource Bundle 'messages' 
ey Messages.properties 
iimessages en.properties 
i application.properties 
> keystore.p12 
a main2.iml 
test 


Figura 7.2: Estrutura do projeto 


O próximo passo é criar dois arquivos nesta pasta que vão 


7.4 INTERNACIONALIZANDO AS MENSAGENS DE ERRO 211 


representar as mensagens que precisamos. Um deles vai ser 
chamado messages en.properties (o prefixo messages e 
mais o locale en ). O segundo vai ser chamado 
messages pt BR.properties (o prefixo messages com o 
locale pt BR ): 


outcoming 
© Capo7Application 
resources 
~i18n 
fi Resource Bundle ‘messages’ 
uimessages en.properties 
wi messages pt BR.properties 
atapplication.properties 
» keystore.p12 
a main2.iml 
I test 
> B target 
o -Qitianore 
Figura 7.3: Arquivos properties 


Precisamos agora utilizar a classe adequada para gerenciar 
esses arquivos. Dentro do Spring, utilizamos uma interface para 
lidar com mensagens chamada MessageSource . Vamos criar 
uma classe de configuração do sistema que forneça uma 
implementação desta interface. Assim, vamos criar uma class 
chamada AppConfig e anotá-la com (configuration . Na 
sequência, vamos criar um método messageSource() que 
retorne um MessageSource e anotá-lo com (Bean : 


package app.car.cap07.config; 
import org.springframework. context. MessageSource; 


import org.springframework.context.annotation.Bean; 
import org.springframework.context.annotation.Configuration; 


212 7.4 INTERNACIONALIZANDO AS MENSAGENS DE ERRO 


@Configuration 
public class AppConfig { 


@Bean 
public MessageSource messageSource() { 
return null; 


} 


Agora, precisamos fazer com que este método retorne uma 
implementação de MessageSource . Esta interface possui muitas 
implementações, mas a que mais se aproxima das nossas 
necessidades é a ReloadableResourceBundleMessageSource , 
pois ela lê os arquivos que estão no classpath e consegue resolver 
quais deles utilizar com base no locale. Basta que façamos a 
configuração do prefixo dos arquivos e ele cuida do restante. No 
nosso caso, como os arquivos estão dentro do diretório i18n e 
têm o prefixo messages , vamos configurar a implementação da 
seguinte forma: 


import org.springframework. context. support .ReloadableResourceBund 
leMessageSource; 


// restante da implementação omitido 


@Bean 

public MessageSource messageSource() { 
ReloadableResourceBundleMessageSource messageSource = new Relo 

adableResourceBundleMessageSource(); 
messageSource.setBasename("ii8n/messages"); 
return messageSource; 


Vamos agora implementar uma forma de extrair o locale 
correto do header Accept-Language . Apenas recapitulando, as 
“preocupações” que temos que ter com essa extração são as 
seguintes: 
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e Uma lista de locales pode ser enviada. Caso o atributo q 
esteja presente em algum deles, também é necessário levar 
em consideração o reposicionamento dentro da lista de 
preferências; 

e Alguns locales podem não ser suportados por nossa 
aplicação; 

e É possível enviar um curinga ( * ) no cabeçalho, indicando 
que qualquer locale é aceito. 


Tendo isso em mente, saiba que o Spring nos disponibiliza 
uma classe que resolve boa parte deste processo, chamada 
AcceptHeaderLocaleResolver . Essa classe define um método 
chamado resolveLocale , que retorna um objeto do tipo 

Locale . Esse objeto estará acessível através da classe 
LocaleContextHolder , método getLocale , que é estático. Por 
isso, é possível recuperar o locale correto a partir de qualquer 
ponto do código. 


Vamos iniciar a implementação do método resolveLocale 
então. Ele recebe como parâmetro um objeto do tipo 
HttpServletRequest eretorna um Locale , assim: 


package app.car.cap07. interfaces. incoming.errorhandling; 


import org.springframework.web.servlet.ii18n.AcceptHeaderLocaleRes 
olver; 


import javax.servlet.http.HttpServletRequest; 
import java.util.Locale; 


public class LocaleResolver extends AcceptHeaderLocaleResolver { 
public Locale resolveLocale(HttpServletRequest request) { 


return null; 


3 
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Vamos anotar essa classe com @Component , para que ela fique 
disponivel para o Spring automaticamente: 


import org.springframework.stereotype.Component; 
// Restante do código omitido 


(Component 
public class LocaleResolver extends AcceptHeaderLocaleResolver { 


public Locale resolveLocale(HttpServletRequest request) { 
return null; 


Agora criaremos duas constantes na nossa classe para 
determinar que nosso locale padrão é o português do Brasil mas 
que também podemos fornecer mensagens em inglês. A primeira 
constante vai se chamar DEFAULT LOCALE e vai ser uma instância 
de Locale com os valores pt e BR. A outra vai se chamar 

ACCEPTED LOCALES e vai conter tanto o DEFAULT LOCALE 
quanto uma nova instância de Locale , parametrizada apenas 
com en: 


package app.car.cap07. interfaces. incoming.errorhandling; 
import java.util.Arrays; 

import java.util.List; 

import java.util.Locale; 


// Restante dos imports omitido 


(Component 
public class LocaleResolver extends AcceptHeaderLocaleResolver { 


private static final Locale DEFAULT_LOCALE = new Locale("pt", 
"BR" Ji 


private static final List<Locale> ACCEPTED_LOCALES = Arrays.as 
List( 
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DEFAULT_LOCALE, 
new Locale("en") 


); 


@Override 
public Locale resolveLocale(HttpServletRequest request) { 
return null; 


} 


Vamos à implementação do método. Vamos utilizar o método 
getHeader do objeto HttpServletRequest para recuperar o 
valor do header Accept-Language . Este header pode não ser 
enviado pelo cliente, ser enviado em branco ou ser enviado com o 
curinga ( * ). Para lidar com os dois primeiros aspectos, vamos 
primeiro incluir a biblioteca commons-lang3 no nosso pom.xml : 
<dependency> 
<groupId>org.apache.commons</groupId> 


<artifactId>commons-lang3</artifactId> 
</dependency> 


Vamos implementar a análise do cabeçalho usando o método 
isBlank , da classe StringUtils : 


import org.apache.commons. lang3.Stringutils; 
public class LocaleResolver extends AcceptHeaderLocaleResolver { 


@Override 
public Locale resolveLocale(HttpServletRequest request) { 
final String acceptLanguageHeader = request.getHeader ("Acce 
pt-Language"); 
if (StringUtils.isBlank(acceptLanguageHeader) || acceptLang 
uageHeader.trim().equals("*")) { 
return DEFAULT LOCALE; 
} 


return null; 
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E vamos usar a classe Locale.LanguageRange para fazer 
parse do valor do cabeçalho. O método parse vai retornar uma 
lista de Locale.LanguageRange , que é uma representação de 
cada Locale já levando em consideração a preferência por cada 
valor (que é determinada pelo conteúdo do atributo q ). Depois de 
fazer isto, podemos submeter tanto a _ lista de 

Locale. LanguageRange quanto a lista de locales suportados para 
o método lookup da classe Locale . Este método compara as 
duas listas para selecionar qual Locale melhor se encaixa nas 
nossas necessidades: 


@Override 
public Locale resolveLocale(HttpServletRequest request) { 

final String acceptLanguageHeader = request.getHeader ("Accept - 
Language"); 

if (StringUtils.isBlank(acceptLanguageHeader) || acceptLanguag 
eHeader.trim().equals("*")) { 

return DEFAULT_LOCALE; 

} 

List<Locale.LanguageRange> list = Locale.LanguageRange.parse(a 
cceptLanguageHeader ); 

Locale locale = Locale.lookup(list, ACCEPTED_LOCALES) ; 

return locale; 


A classe finalizada fica assim: 
package app.car.cap07.interfaces.incoming.errorhandling; 


import org.apache.commons.lang3.StringUtils; 

import org.springframework. stereotype. Component; 

import org.springframework.web.servlet.ii18n.AcceptHeaderLocaleRes 
olver; 


import javax.servlet.http.HttpServletRequest; 
import java.util.Arrays; 

import java.util.List; 

import java.util.Locale; 


@Component 
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public class LocaleResolver extends AcceptHeaderLocaleResolver { 


private static final Locale DEFAULT_LOCALE = new Locale("pt", 
"BR" Jy 


private static final List<Locale> ACCEPTED_LOCALES = Arrays.a 
sList( 


DEFAULT_LOCALE, 
new Locale("en") 


); 


@Override 
public Locale resolveLocale(HttpServletRequest request) { 
final String acceptLanguageHeader = request.getHeader ("Ac 
cept-Language"); 
if (StringUtils.isBlank(acceptLanguageHeader) || acceptLa 
nguageHeader.trim().equals("*")) { 
return DEFAULT_LOCALE; 
} 
List<Locale.LanguageRange> list = Locale.LanguageRange.pa 
rse(acceptLanguageHeader ) ; 
Locale locale = Locale.lookup(list, ACCEPTED _LOCALES) ; 
return locale; 


Agora, vamos ajustar a nossa classe DefaultErrorHandler 
para que os códigos de erro sejam ajustados para o Locale 
Vamos começar revendo a implementação do método 
handleMethodArgumentNotValid : 


@ExceptionHandler (MethodArgumentNotValidException.class) 
@ResponseStatus(HttpStatus.BAD_REQUEST ) 

public ErrorResponse handleMethodArgumentNotValid(MethodArgumentN 
otValidException ex) { 


List<ErrorData> messages = ex 
.getBindingResult() 
.getFieldErrors() 
.stream() 
.map(fe -> new ErrorData(fe.getDefaultMessage())) 
.collect(Collectors.toList()); 
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return new ErrorResponse(messages) ; 


fa 


Nossa tarefa é modificar a linha onde o método map é 
chamado para que, em vez de instanciar um ErrorData neste 
momento, vamos fazer a chamada para um novo método que será 
criado. Assim sendo, vamos criar o método getMessage , que 
recebe um FieldError como parâmetro e retornar um 
ErrorData : 


@ExceptionHandler (MethodArgumentNotValidException.class) 
@ResponseStatus(HttpStatus.BAD_ REQUEST) 

public ErrorResponse handleMethodArgumentNotValid(MethodArgumentN 
otValidException ex) { 


List<ErrorData> messages = ex 
.getBindingResult() 
.getFieldErrors() 

.stream() 
.map(this::getMessage) 
.collect(Collectors.toList()); 


return new ErrorResponse (messages); 


private ErrorData getMessage(FieldError fieldError) { 


return null; 


Como vimos antes, cada FieldError tem uma lista de 
codes que vai desde um código que é mais específico até um 
genérico. Vejamos os códigos que foram retornados antes: 
"codes": [ 
"NotNull.travelRequestInput.passengerId", 
"NotNull.passengerId", 


"NotNull.java.lang.Long", 
"NotNull" 
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Dessa forma, é possível criar uma validação para quando o 
campo passengerId da classe travelRequestInput for nulo; 
quando apenas o campo passengerId for nulo (ou seja, de 
qualquer classe); quando qualquer campo do tipo 
java. lang.Long for nulo e, finalmente, quando qualquer campo 
for nulo. Baseado nestes códigos, podemos criar mensagens de 
validação para qualquer campo, mas vamos criar especificamente 
para o caso mais amplo possível, ou seja, quando o código for 

NotNull . Para isso, vamos abrir os arquivos 
messages pt BR.properties e messages en.properties e 
criar valores para a chave NotNull , cada um deles em um idioma 
específico. Assumindo que o português do Brasil vai ser o nosso 
idioma padrão para as mensagens, vamos primeiro abrir o arquivo 
messages pt BR.properties e colocar o seguinte conteúdo: 


NotNull=0 campo não pode ser nulo 


E vamos proceder de forma semelhante com o arquivo 


messages en.properties: 


NotNull=The field must not be null 


Resta um último detalhe: se várias mensagens similares forem 
retornadas, não vamos conseguir saber a qual campo elas se 
referem. É possível parametrizar as mensagens de erro colocando 
índices para os parâmetros. Vamos novamente alterar o conteúdo 
dos arquivos da seguinte forma: 


NotNull=0 campo (0) não pode ser nulo 
E 
NotNull=The field {0} must not be null 


Para implementar a busca do código, vamos injetar o 
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MessageSource na classe, utilizando a anotação @Autowired : 
package app.car.cap07.interfaces.incoming.errorhandling; 


import org.springframework.beans.factory.annotation.Autowired; 
import org.springframework. context. MessageSource; 


//Restante dos imports omitido 


@RestControllerAdvice 
public class DefaultErrorHandler { 


@Autowired 
private MessageSource messageSource; 


// Restante do código omitido 


A interface MessageSource oferece três implementações do 
método getMessage : 


e A primeira recebe o código da mensagem, um array de 
parâmetros para a mensagem, uma String com a mensagem 
padrão e o Locale . Caso a mensagem não seja 
encontrada, retorna a mensagem padrão; 

e A segunda recebe o código da mensagem, um array de 
parâmetros e o Locale . Caso a mensagem não seja 
encontrada, lança uma NoSuchMessageException ; 

e A terceira recebe uma implementação da interface 


MessageSourceResolvable eo Locale. 


No nosso caso, podemos aproveitar que o FieldError 
implementa a interface MessageSourceResolvable . Desta 
forma, tudo o que temos a fazer é utilizar o método getMessage 
passando como parâmetro o FieldError eo Locale . Este 
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ultimo pode ser obtido a partir da classe LocaleContextHolder , 


que provê um método estático chamado getLocale (por baixo 


dos panos, ele vai retornar o resultado do método que codificamos 


na classe LocaleResolver ). A classe toda, finalizada, fica assim: 


package app.car.cap07. interfaces. incoming.errorhandling; 


import 
import 
import 
import 
import 
import 
on; 

import 
import 
import 
ce; 


import 
import 


org 


org. 
org. 
org. 
org. 
org. 


org 


org. 


org 


jav 
jav 


.springframework.beans.factory.annotation.Autowired; 
springframework. context. MessageSource; 
springframework.context.ii8n.LocaleContextHolder; 
springframework.http.HttpStatus; 
springframework.validation.FieldError; 
springframework.web.bind.MethodArgumentNotValidExcepti 


.springframework.web.bind.annotation.ExceptionHandler; 
springframework.web.bind.annotation.ResponseStatus; 
.springframework.web.bind.annotation.RestControllerAdvi 


a.util.List; 
a.util.stream.Collectors; 


@RestControllerAdvice 
public class DefaultErrorHandler { 


@Autowired 
private MessageSource messageSource; 


@ExceptionHandler (MethodArgumentNotValidException.class) 

@ResponseStatus(HttpStatus.BAD REQUEST) 

public ErrorResponse handleMethodArgumentNotValid(MethodArgume 
ntNotValidException ex) { 


List<ErrorData> messages = ex 


.getBindingResult() 
.getFieldErrors() 

.stream() 
.map(this::getMessage) 
.collect(Collectors.toList()); 


ret 


urn new ErrorResponse (messages); 
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private ErrorData getMessage(FieldError fieldError) { 
return new ErrorData(messageSource.getMessage(fieldError, L 
ocaleContextHolder.getLocale())); 


> 
Vamos testar novamente com o Postman, passando primeiro o 


locale en no cabeçalho Accept - Language : 


Postman 


File Edit View Help 


EE MyWorkspace ~ & Invite (G 








local-secure 
poo? Create Travel Request o + e. 
+ Create Travel Request EM comments (¢ 
POST v  ({host})/travelRequests 
e Headers (11) e 
v Headers (2) 
KEY VALUE DESCRIPTION sss Bul 
Content-Type application/json 
Accept-Language en 
> Temporary Headers (9) O 
Body ers (11) Status; 400 Bad Request Time: 642ms Size: 5718 
Pretty SON v» 5 
1 A 
2 “errors”: [ 
3 { 
4 "message": "The field passengerId must not be null” 
5 i, 
6 { 
7 "message": "O campo origin não pode estar em branco" 
8 i, 
9 { 
10 "message": "O campo destination não pode estar em branco" 
11 } 
12 ] 
3 q 
EI a Fei =» Bootcamp Build Browse 





Figura 7.4: Teste com Locale en 
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Observe que a mensagem do passengerId veio em inglês, 
enquanto as outras duas vieram em português. Isso acontece 
porque não configuramos a mensagem da validação da anotação 
ONotEmpty e o sistema usou as mensagens padrão (ou seja, as que 
estavam diretamente nas anotações). 


Vamos abrir novamente os arquivos de propriedades e 
configurar as mensagens, começando pelo 


messages pt BR.properties: 


NotNull=0 campo (0) não pode ser nulo 
NotEmpty=0 campo {0} não pode estar em branco 


Agora o arquivo messages en.properties : 


NotNull=The field {0} must not be null 
NotEmpty=The field {0} must not be empty 


Vamos testar novamente: 
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Postman 


# Invite 





local-secure 


por Create Travel Request o + % 
> Create Travel Request a Comments (0 
= rd 








e Headers (11) . Setti 
v Headers (2 
KEY VALUE DESCRIPTION +s. Bul 
Content-Type application/json 
Accept-Language en 


> Temporary Headers (9) O 





Body (11) tatus: 400 Bad Request 1200ms Size: 5598 
Pretty SON + 5 
1 { 
2 "errors": [ 
3 { 
- "message": "The field destination must not be empty” 
5 h 
6 { 
7 "message": "The field origin must not be empty” 
8 }, 
9 { 
10 "message": "The field passengerId must not be null" 
11 } 
12 ] 
3 J 
E q fel © Bootcamp Build 





Figura 7.5: Novo teste com Locale en 


Agora, vamos ajustar o cabeçalho para locale pt-BR: 


7.4 INTERNACIONALIZANDO AS MENSAGENS DE ERRO 225 


Postman 


File Edit View H 


ms MyWorkspace ~ 4 Invite 





local-secure 
poor Create Travel Request o + ce 
+ Create Travel Request E comments (0 
POST X {(host}}/travelRequests 
e Headers (11) e et 
v Headers (2) 
KEY VALUE DESCRIPTION c.. Bull 
Content-Type application/json 
Accept-Language pt-BR 
» Temporary Headers (9) O 
Body ers (11) s: 400 Bad Request Time: 6.84s Size: 5718 
Pretty f j JSON + = 
1 ff 
2 "errors": [ 
3 
= "message": "O campo passengerId não pode ser nulo" 
5 L 
6 { 
7 "message": “O campo destination não pode estar em branco” 
8 1, 
9 { 
10 "message": "O campo origin não pode estar em branco” 
11 } 
12 ] 
3 J 
ED Q A Er Bootcamp Bulld Browse 


Figura 7.6: Teste com Locale pt-BR 


Também ficou bom. O último teste que precisamos fazer é com 
um locale não utilizado no sistema. Vamos colocar zh (Chinês) 
para verificar o que acontece: 
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Postman 


ss MyWorkspace ~ è, Invite 








local-secure 
pony Create Travel Request o + | on 
+ Create Travel Request EM comments (0 
POST v  {{host)}/travelRequests 
e Headers (11) . atti 
v Headers (2) 
KEY VALUE DESCRIPTION eee Bull 
Content-Type application/json 
Accept-Language zh 
> Temporary Headers (9) O 
Body (11) Status: 400 Bad Request Time: 647ms Size: 5598 
Pretty SON v» = 
1 df 
2 “errors”: [ 
3 
4 "message": "The field origin must not be empty” 
5 i, 
6 { 
7 "message": "The field passengerId must not be null" 
8 i, 
9 { 
10 "message": “The field destination must not be empty" 
11 } 
12 | 
3 J 
E) cal tr Bootcamp uiid Browse 





Figura 7.7: Teste com Locale zh 


Por que isso aconteceu? Quando codificamos o nosso 
LocaleResolver , na hora de fazer o lookup , o locale chinês não 
estava na nossa lista de locales suportados. Então, o método 
retornou null . Isso fez com que o LocaleContextHolder 
retornasse o locale onde o sistema está configurado - no meu caso, 
inglês americano. 
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Para que isso não aconteça, precisamos ajustar a nossa classe 
LocaleResolver , no ponto onde está o método lookup . Vamos 
utilizar a classe Optional do Java para, caso o locale não tenha 
sido retornado do método lookup , utilizarmos o locale padrao. 
Entao, o método passa a ficar assim: 


package app.car.cap07.interfaces.incoming.errorhandling; 


// Restante dos imports omitidos 
import java.util.Optional; 


@Component 
public class LocaleResolver extends AcceptHeaderLocaleResolver { 


private static final Locale DEFAULT_LOCALE = new Locale("pt", 
"BR" ye 


private static final List<Locale> ACCEPTED_LOCALES = Arrays.a 
sList( 


DEFAULT_LOCALE, 
new Locale("en") 


); 


@Override 
public Locale resolveLocale(HttpServletRequest request) { 
final String acceptLanguageHeader = request .getHeader ("Ac 
cept-Language"); 
if (StringUtils.isBlank(acceptLanguageHeader) || acceptLa 
nguageHeader.trim().equals("*")) { 
return DEFAULT_LOCALE; 
} 
List<Locale.LanguageRange> list = Locale.LanguageRange.pa 
rse(acceptLanguageHeader ); 
Locale locale = Locale.lookup(list, ACCEPTED _LOCALES) ; 
return Optional.ofNullable(locale).orElse(DEFAULT LOCALE) 


Com essa modificação, vamos reiniciar o sistema e testar 
novamente. O resultado da requisição fica assim: 
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e Edit View Help 


Te = 


per? Create Travel Request o + ce 


+ Create Travel Request 


POST ~  {(host)}/travelRequests 


e Headers (11) 
v Headers (2 
KEY 
Content-Type 


Accept-Language 


> Temporary Headers (9) O 





Body ers (11) 
Pretty 
1 ff 
2 "errors": [ 
3 
4 "message": 
5 } 
6 { 
7 "message": 
8 }, 
9 { 
10 "message": 
11 } 
12 | 
13 df 
E) A 


&, Invite O 


s= My Workspace ¥ 


VALUE 
application/json 


zh 


400 Bad Request 


ul 


"O campo passengerId não pode ser nulo" 


"O campo destination não pode estar em branco” 


"O campo origin não pode estar em branco 


© Bootcamp 


Figura 7.8: Novo teste com Locale zh 


7.5 COMO 


RETROCOMPATÍVEL 


CRIAR 
(OU: 


VERSIONAR UMA API) 


local-secure 


DESCRIPTION 


UMA 





Comments (! 


API 


COMO 


Nossa API está crescendo. É provável que o negócio em si a 


acompanhe no crescimento, e isso vai gerando novas demandas 
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para a API. Com novas demandas, a API precisa ser 
evoluida/melhorada. Isso faz com que uma API muitas vezes nao 
possa mais ser usada. 


Vamos ver um exemplo na própria API que construímos, 
/travelRequests . Uma request típica seria assim: 


{ 
"nassengerlId": 1, 
"destination": "Avenida Faria Lima, 1300", 
"origin": "Avenida Paulista, 100" 

} 


Se o time de negócios decidisse que, além do endereço, 
precisamos do CEP em um campo separado, poderíamos desenhar 
uma nova request para ser mais ou menos da seguinte forma: 


{ 
"nassengerlId": 1, 
"destination": { 
"name": "Avenida Faria Lima, 1300", 
"zipCode":"05426-100" 
x, 
"origin": "Avenida Paulista, 100" 
} 


Mas existe um problema fundamental ai: os clientes atuais da 
API esperam que o campo destination seja uma String, não um 
objeto mais complexo. Isso faria com que a API deixasse de 
funcionar para estes clientes já existentes, e isso faria com que esta 
API não fosse retrocompatível. A retrocompatibilidade é muito 
importante em ambientes onde você não conhece os usuários da 
sua API ou você não tem controle sobre eles. Por exemplo, se você 
tiver um aplicativo mobile que consulta a sua API, pode ser que os 
usuários do aplicativo passem um bom tempo sem atualizar a 
versão dele mas, mesmo assim, você deseja que estas versões mais 
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antigas continuem funcionando sem forçar a atualização. 


Quando uma API é criada para ser retrocompatível, algumas 
regras devem ser seguidas: 


e Não se pode modificar campos simples para se tornarem 
complexos; 

e Não se pode introduzir novos campos que sejam 
obrigatórios; 

e Não se pode criar regras restringindo valores aceitos em 
um campo (por exemplo, tomar um campo que aceite até 5 
caracteres e fazer com que passe a aceitar até 3); 

e Não se pode introduzir qualquer espécie de parâmetro que 
seja obrigatório; 

e Não se pode alterar as URLs; 

e Não se pode alterar nomes de campos (tanto na request 
quanto na response). 


Como via de regra, é mais fácil dizer o que pode ser feito em 
uma API que não provoca erros na retrocompatibilidade: 


e Criação de novos campos não obrigatórios; 

e Flexibilização de regras de validação (por exemplo, um 
campo que aceite até 5 caracteres passa a aceitar 10); 

e Criação de novas URLs na API. 


Como você pode observar, é mais difícil deixar uma API 
retrocompatível do que o contrário. Esta técnica de manutenção de 
uma API para que não haja quebra dos clientes é semelhante ao 
incremento de uma minor version em um software qualquer. Se 
fôssemos mesmo atribuir uma versão à nossa API, poderíamos 
dizer que é esperado que os clientes que foram feitos para utilizar a 
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versão 1.0 da API continuem funcionando corretamente quando 
a API vai para a versão 1.1, sem qualquer alteração. O mesmo já 
não pode ser dito se a API for para uma suposta versão 2.0 :a 
major version é incrementada quando há quebra da 
compatibilidade - não sendo desta forma retrocompatível. 


Não é desejável haver quebra da compatibilidade; portanto 
implementamos uma estratégia de versionamento da API para 
que ao menos possamos manter versões da API executando em 
paralelo. A estratégia de manter versões rodando em paralelo nos 
permite criar estratégias para executar um planejamento de phase 
out nos clientes, ou seja, avisá-los de que eles possuem um certo 
prazo para atualizar para a versão mais recente da API enquanto a 
antiga não deixa de funcionar. 


No aspecto técnico, para versionar as APIs criamos uma forma 
do cliente informar ao servidor qual versão da API gostaria de 
usar. As principais formas de fazer isso são as seguintes: 


e Modificar a URL dos serviços para incluir a versão. Ex: 
/v1/travelRequests 

e Criar um query param para fornecer a versão. Ex: 
/travelRequests?version=1 


e Criar um header para fornecer a versão. 


Cada uma dessas formas tem vantagens e desvantagens, que 
vamos investigar mais a fundo a seguir. 


Versionamento através de mudança de hostnames 
Exemplo: https://vl.api.car.com.br/travelRequests 


Esta estrutura é a mais flexível de todas, porém também é a que 
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tem mais “potencial para desastre”. Com essa estrutura é possível 
recriar por completo uma API - pois se o host muda, é como se 
fosse uma nova integração. Porém, ao forçar o cliente ao criar essa 
nova integração, todo um overhead gerado por esse processo é 
assumido. Parte desse overhead significa configurar possíveis 
servidores proxy, regras de roteamento Apache/nginx etc. 
Contudo, do lado de quem provê a API, estas mesmas dificuldades 
podem ser transformadas em facilidades, pois permitem que as 
APIs estejam localizadas em máquinas ou datacenters diferentes, e 
até mesmo que sejam escritas em linguagens diferentes. Ou seja: 
efetivamente, é como oferecer APIs totalmente novas. 


Pró: 
e Permite reestruturar por completo a estrutura. 


Contra: 


e Pode prejudicar demais os clientes quando a mudança é 
realizada, talvez até os forçando a manter estruturas 
diferentes. 


Versionamento pela URL 
Exemplo: https://api.car.com.br/v1/travelRequests 


Esta é uma das técnicas mais adotadas quando se fala a respeito 
de versionamento de APIs, por ser uma das mais diretas. A API 
que é versionada desta forma pode decidir se força o cliente a 
informar a versão ou não. Por exemplo, a mesma API pode estar 
disponível em https://api.car.com.br/vl/travelRequests e 
https://api.car.com.br/travelRequests, sendo que, nesta última, o 
servidor adota a última versão como padrão. Tal feito não precisa 
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necessariamente ser codificado diretamente na aplicação; basta que 
o fornecedor da API crie uma regra no balanceador de carga 
(como o já mencionado nginx, por exemplo). Isso pode ou não ser 
fácil/conveniente, mas é uma opção para o caso de não ser 
desejável criar o roteamento diretamente na aplicação. 


Um aspecto que torna delicada a adoção desse modelo é o uso 
de HATEOAS, pois desta forma o cliente não tem a flexibilidade 
para escolher quais versões utilizar de quais links, ou seja, ele pode 
ser forçado por um link HATEOAS a utilizar uma versão diferente 
da desejada. O mesmo vale para a estratégia de, caso a versão não 
esteja presente, utilizar a última: um link que tenha uma natureza 
mais permanente pode criar o mesmo conflito no cliente, onde este 
referencia um link contando com uma determinada versão e esta 
passa por upgrade internamente. 


Em todos os casos citados, fica claro também que a 
coexistência de recursos com diferentes versões pode ser complexa, 
uma vez que um serviço pode passar por um upgrade e outro, não. 
Desta forma, em um cenário com vários serviços convivendo em 
um mesmo ecossistema fica clara a necessidade de se ter alguma 
forma de gerenciamento das versões dos serviços. 


Por último, deixo claro que, conforme explanado ao longo 
deste livro, o versionamento por URLs não é RESTful. Isso 
significa que os serviços que adotam este modelo de 
versionamento não estão 100% de acordo com a especificação 
REST original (FIELDING, 2000). Assim sendo, tal uso de 
versionamento pode acabar levando as APIs a destoarem do 
modelo como um todo e paulatinamente perderem a característica 


da usabilidade. 


234 7.5 COMO CRIAR UMA API RETROCOMPATÍVEL (OU: COMO VERSIONAR 
UMA API) 


O QUE SIGNIFICA A PALAVRA RESTFUL? 


O sufixo ful depois de REST é uma forma da língua inglesa de 


adaptar ou transformar um substantivo em um adjetivo. Para 


ficar mais claro, temos como exemplos a palavra color (cor) e 
colorful (colorido). Da mesma forma, entenda-se REST como 
um substantivo e RESTful como um adjetivo. Na maior parte 
dos contextos, pode ser usada de maneira intercambiável. 





Prós: 


e Torna a versão utilizada óbvia; 
e Fácil de criar regras de roteamento. 


Contras: 


Quebra HATEOAS; 

Quebra links permanentes; 

Não é RESTful; 

Coexistência entre recursos de versões diferentes. 


Versionamento por query params 
Exemplo: https://api.car.com.br/travelRequests?v=1 


Uma maneira substancialmente mais simples de versionar 
APIs seria através de query params. No entanto, esta facilidade não 
perduraria por muito tempo, pois além de apresentar alguns dos 
problemas demonstrados pelo versionamento via URL, acrescenta- 
se também um problema com o roteamento (alguns balanceadores 
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de carga podem não o reconhecer como um método de 
roteamento). 


Um problema ainda mais grave com esta abordagem é que os 
query params são historicamente utilizados apenas no método 
GET. É um pouco mais comum hoje em dia outros métodos 
suportarem, mas nota-se que essa não é uma boa prática e deve ser 
evitada. Observa-se que algumas bibliotecas não suportam isso, 
como a Fuel (de desenvolvimento Android): 
https://github.com/kittinunf/fuel/issues/231. 


r 


Pró: 


e Método simples 


Contras: 


e Difícil de criar regras de roteamento 
e Nem todos os métodos HTTP e bibliotecas suportam 
e Não é RESTful 


Versionamento por um cabeçalho customizado 
Exemplo: 
Accept-Version: v1;q=0.8,v2;q=0.6 
https://api.car.com.br/travelRequests 


Ao passo que o versionamento por URL não é RESTful, este 
mecanismo é. A passagem de cabeçalhos no protocolo HTTP 
demonstra como funciona o tráfego de metadados entre o cliente e 
o fornecedor, e o uso de um cabeçalho para informar a versão é 
uma excelente demonstração disso. 
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Para efeitos de comparação, lembre-se de que temos outros 
cabeçalhos de negociação de conteúdo disponíveis na própria 
especificação HTTP: 


e Accept 
e Accept-Language 
e Accept-Encoding 


e outros 


Assim sendo, um cabeçalho do tipo Accept-Version (ou 
similar) estaria muito próximo daquilo que já está embutido no 
protocolo HTTP, ainda mais se ele tivesse o caráter de negociável 
(conforme ocorre com o Accept-Language , por exemplo). 


Isso teria várias vantagens. A primeira delas é que, ao utilizar 
HATEOAS ou links permanentes, o usuário teria plena 
possibilidade de determinar novas versões utilizando os mesmos 
links, criando total flexibilidade. 


No entanto, o fato de ser customizado faz com que o usuário 
precise ser informado explicitamente sobre o que inserir como 
informação de versão, ou não inserir qualquer informação e seguir 
a abordagem de utilizar a última versão (tendo os mesmos 
problemas que foram explicitados na seção de versionamento pela 
URL). Além disso, o próprio fornecimento do cabeçalho não é 
óbvio, já que no HTTP os cabeçalhos costumam seguir uma 
natureza mais opcional. 


Os dois problemas poderiam ser resolvidos ao mesmo tempo 
se o cabeçalho fosse tornado obrigatório. Isso faria com que a API 
perdesse um pouco da sua usabilidade, mas ganharia mais 
resiliência neste aspecto do versionamento. 
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Pros 


e É RESTful; 
e Pode oferecer um modelo mais flexível de negociação de 
versões. 


Contras 


e Não é padronizado / óbvio; 

e Deixa o cliente livre para não especificar qual a versão; 

e Pode quebrar HATEOAS; 

e Pode apresentar inconsistências entre versões diferentes de 
recursos. 


Versionamento pelo cabeçalho Accept 
Exemplo: 
Accept: application/vnd.travelrequest+json;version=1.0 
https://api.car.com.br/travelRequests 


Em termos de elegância, este é o melhor formato de todos, pois 
utiliza o próprio mecanismo de negociação de conteúdo REST 
para negociar também a versão. Perde em termos da negociação de 
versão que pode ser embutida em um cabeçalho customizado, mas 
ganha na padronização. 


Entretanto, por requerer customização sobre os próprios media 
types (uma vez que as informações de versão são anexadas a estes, 
conforme visto no exemplo), esta vantagem pode ser rapidamente 
transformada em desvantagem ao passo que pode ser prejudicial 
para algumas bibliotecas de clientes. 
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Pros 


e Eo formato mais RESTful; 
e Torna mais óbvia a questão do versionamento. 


Contras 


e Pode nao ser completamente compativel com as bibliotecas 
de clientes; 

e Pode interferir no funcionamento correto da negociação de 
conteúdo; 

e Não oferece tanta flexibilidade a respeito de qual versão 
utilizar. 


Finalmente, qual modelo escolher? 


Todos os formatos vistos possuem vantagens e desvantagens - 
no fim das contas, trata-se de analisar o seu ecossistema (em 
termos de ferramentas utilizadas, clientes etc.) e verificar qual 
formato encaixa-se melhor. No meu ponto de vista, a abordagem 
com o cabeçalho customizado parece a opção com menos pontos 
contra - ou ao menos, a opção em que é mais fácil contornar os 
pontos contra. 


Conclusão 


Este capítulo tem a missão de ser um divisor de águas dentro 
do livro. Até aqui, abordamos as questões mais básicas e óbvias de 
desenvolvimento de APIs com todo o básico necessário para 
realizar o desenvolvimento. A partir deste capítulo, passamos a 
falar sobre conteúdo mais avançado e que realmente faz com que 
uma API seja fácil de usar e esteja pronta para os desafios que 
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aparecerão uma vez que o grande público passe a utilizá-la. Mas 
esse foi apenas o primeiro passo; precisamos falar mais sobre 
outras questões, como documentação, monetização e como 
abordar questões como o throttling. Vamos em frente? 
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CapituLo 8 


DOCUMENTANDO A API 


“Embora a memória e o raciocínio sejam duas faculdades 
essencialmente diferentes, uma só se desenvolve completamente com 
a outra.” - Jean-Jacques Rousseau 


Uma das partes mais importantes de se criar e manter uma API 
é a partir de sua documentação. Afinal, se uma API é a interface 
para que um programa interaja com outro da melhor forma 
possível, a documentação é a ferramenta que garante que pessoas 
aprendam a usar a API da melhor forma possível. 


Uma boa documentação é suficientemente inteligível para 
atingir seu público-alvo em cheio. Algumas são dirigidas a pessoas 
com viés mais técnico, como desenvolvedores, arquitetos, analistas 
etc. Já outras têm como alvo pessoas com viés mais relacionado ao 
negócio, como product owners, gerentes e até algumas do chamado 
C-level. Isso pode provocar diferenciação nos meios utilizados para 
documentar a API; as documentações produzidas para pessoal 
técnico precisam de riqueza de detalhes técnicos e facilidade de 
interação. Já as documentações produzidas para pessoal de negócio 
detalham com riqueza o propósito das APIs que estão sendo 
tratadas por elas e como o usuário final pode ser impactado. 


Um grande desafio para manter uma boa documentação de 
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APIs é a rapidez com que esta pode ficar defasada. Isso geralmente 
acontece quando a documentação é gerada de forma dissociada do 
código, isto é, o desenvolvedor da API realiza a manutenção e, 
quando publicada, atualiza a API. Esta segunda etapa, em meio às 
preocupações do dia a dia, pode facilmente ser deixada de lado, 
gradualmente tornando a documentação inútil por não mais 
refletir a realidade. 


Para contornar o problema, alguns frameworks foram criados 
ao longo do tempo e surgiu o conceito de documentação viva. A 
documentação que é chamada desta forma é gerada junto ao 
código (muitas vezes, esta é gerada pelo código), de forma que o 
código e sua documentação não podem ser dissociados. Isso faz 
com que a atualização do código e da documentação seja uma 
coisa só, e a documentação permaneça sempre atualizada, já que a 
tarefa de atualizá-la não é separada da tarefa de atualizar o código 
que a acompanha. 


8.1 CRIANDO UMA DOCUMENTAÇÃO VIVA 
COM SWAGGER/OPENAPI 


Em Java, uma forma muito prática para se atingir uma 
documentação viva é através do uso de anotações. Um framework 
que adotou esta técnica com maestria foio Swagger (disponível 
em https://swagger.io/), que desde 2010 esta disponível para 
realizar esta tarefa. Em 2015, a especificação Swagger foi doada 
para a Linux Foundation e foi renomeada para OpenAPI, tendo 
em vista o objetivo de padronizar a maneira como APIs REST são 
documentadas. Hoje, é um dos frameworks mais populares para 
criação de documentação viva. 
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Para o Swagger comecar a funcionar, vamos incluir a 
dependência dele no pom.xml do nosso projeto: 
<dependency> 
<groupId>org.springdoc</groupId> 
<artifactId>springdoc-openapi-ui</artifactId> 


<version>1.2.32</version> 
</dependency> 


Além disso, como havíamos alterado nosso projeto para 
proteger todas as URLs, precisamos criar regras especiais para 
dispensar as URLs específicas do Swagger de autenticação. As 
URLs são: 


e /swagger-ui.html 
e /swagger-ui/ (e quaisquer outras URLs derivadas) 
e /v3/api-docs/ (e derivadas) 


Para realizar a liberação, vamos abrir novamente o método 
void configure(HttpSecurity http) , na classe 
SecurityConfig . Ele deve estar com o seguinte conteúdo: 


@Override 
protected void configure(HttpSecurity http) throws Exception { 
http.csrf().disable(); 


http.sessionManagement ( ) 
.sessionCreationPolicy(SessionCreationPolicy.STATELESS) ; 


http 
.authorizeRequests() 
.anyRequest() 
.authenticated() 
.«and() 
.httpBasic(); 


Vamos alterar a última declaração (a que contém 
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authorizeRequests ) para permitir que as URLs do Swagger 
sejam liberadas. Primeiro, precisamos incluir uma chamada para 
antMatchers , que recebe as diversas URLs com uma notação de 
padrões. Com esses padrões, as URLs que vão incluir derivadas 
podem utilizar ** para refletir esta necessidade. Por exemplo, 
/swagger-ui/ vai ficar /swagger-ui/** . Assim sendo, a 
chamada fica assim: 


http 
.authorizeRequests() 
.antMatchers("/swagger-ui.html", "/swagger-ui/**", "/v3/api 
-docs/**") 
.anyRequest() 
.authenticated() 
.«and() 
.httpBasic(); 


Por último, incluímos apenas uma chamada para 
permitAll() logo abaixo de antMatchers para declarar que 
estas URLs não precisam de autenticação. Então teremos: 


http 
.authorizeRequests() 
.antMatchers("/swagger-ui.html", "/swagger-ui/**", "/v3/api 
-docs/**") 
.permitall() 
.anyRequest() 
.authenticated() 
.«and() 
.httpBasic(); 


Este é o básico. Inicialize a aplicação e navegue para 
https://localhost:8080/swagger-ui.html : 
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€ > Œ A Nokseewe | locathast-s080/swegye lex hr Higunta (VI opui-docs fura ge: & @ Incognito 





OpenAPI definition ? ™ 


Servers, 


intps:Mocalhost:8080 - Generated server url ~ 


driver-api 
EEE (drivers 
[ESA /drivers 
| cer | (drivers /{id) — 
EE Jarivers/{id} 

| oevere | /drivers/{id} 
Haron | /drivers/{id} 
passenger-api 
km /passengers 
Post | /passengers 

f ser | /passengers/{id} 
EEE oassenaers/(id) j 

Figura 8.1: Tela inicial do Swagger 

















Observe que todas as APIs que criamos anteriormente já foram 
detectadas e estão implantadas. Por exemplo, se eu clicar na 
posição do GET /drivers/{id} ,vou ver a seguinte tela: 
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é CA Notsecure | localhost eqger-uifindezht figUls/v3 /epidotshwegge a fdriversa 4Orive jr O incognito 
| cer | /drivers/{id} 

Parameters Try it out | 

| 

Name Description 

id é wens 

integer 

(pata) 

Responses 

Code Description Links 

200 No inks 


detault response 


id“: ©, 


"name": “string” 
"birthDate™: "2828-02-29720:41:33.0182” 





400 No links 


errors": | 
t 
“message”: “string” 





Figura 8.2: Tela do Swagger para GET em /drivers/{id} 


O que falta aqui é enriquecer a documentação com descrições 
acerca do que representam os dados. Como já mencionado 
anteriormente, isso é feito através de anotações. Vamos abrir a 
classe DriverAPI e incluir a anotação @Tag , fornecendo os 
parâmetros name (que declara o nome da API) e description 
(que vamos usar para fornecer uma descrição detalhada do que se 
trata a APT): 


import io.swagger.v3.0as.annotations.tags.Tag; 


246 8.1 CRIANDO UMA DOCUMENTAÇÃO VIVA COM SWAGGER/OPENAPI 


//Outros imports omitidos e anotações omitidas 
@Tag(name = "Driver API", description = "Manipula dados de motori 
stas.") 


public class DriverAPI { 


//Código omitido 


Ao inicializar o sistema novamente e acessar a tela da 
OpenAPI, vemos a mudança: 


Servers 


https://localhost:8080 - Generated server url v 


Driver API Manipula dados de motoristas. 


Figura 8.3: Documentação da API de motoristas mais detalhada 














Para detalhar melhor cada operação da API, utilizamos a 
anotação @Operation , que tem um atributo chamado 
description . Vamos ver como isso funciona ao anotar o método 


findDriver : 

import io.swagger.v3.0as.annotations.*; 
//Restante do código omitido 
@GetMapping("/drivers/{id}") 


@Operation( 
description = "Localiza um motorista especifico" 
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public Driver findDriver( @PathVariable("id") Long id) { 
return driverRepository.findById(id).orElseThrow(() -> new Res 
ponseStatusException(HttpStatus.NOT FOUND)); 


} 


Vejamos como ficou: 


Driver API manipula dados de motoristas. 


REM /drivers 
/drivers 
/drivers/{id} 


Localiza um motorista especifico 














Parameters 








Figura 8.4: /drivers/{id} com documentação 


Vamos incrementar a documentação desta operação com as 
descrições dos retornos, ou seja, quais são os códigos de status 
utilizados nos retornos e o que retorna nesses casos. Vamos fazer 
isso utilizando o atributo responses da anotação (operation. 
Como este atributo recebe um array de @ApiResponse , vamos 
utilizar os atributos desta anotação para realizar o descritivo: 


import io.swagger.v3.0as.annotations.responses.ApiResponse; 


@GetMapping("/drivers/{id}") 


@Operation( 
description = "Localiza um motorista especifico", 
responses = { 
@ApiResponse(responseCode = "200", description = "Caso o 
motorista tenha sido encontrado na base"), 
@ApiResponse(responseCode = "404", description = "Caso o 
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motorista nao tenha sido encontrado") 


} 


) 
public Driver findDriver( @PathVariable("id") Long id) { 


return driverRepository.findById(id).orElseThrow(() -> new Res 
ponseStatusException(HttpStatus.NOT_FOUND) ); 


} 


Isso se transforma no seguinte: 
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250 


Code 


200 


400 


404 


Description 


Caso o motorista tenha sido encontrado na base 


Media type 


application/json v 


Controls Accept header. 


Example Value Schema 


{ 
"id": 0, 


"name": “string”, 
“birthDate": "2020-02-29721:46:04.901Z" 





default response 


Media type 
+j v 


Example Value Schema 


{ 


"errors": [ 


"message": "string" 





Caso o motorista não tenha sido encontrado 


Media type 
application/json v 


Example Value Schema 


"id": 0, 


"name": “string”, 
"birthDate": "2020-02-29721:46:04.905Z2" 





Figura 8.5: /drivers/{id} com documentação de erros, mas ainda com algo errado 
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Observe que o mapeamento está errado, pois ele detectou que 
uma resposta 404 seria dada com o retorno usual. Precisamos 
incrementar o mapeamento para que a resposta do status 404 
esteja com o objeto de erro. 


Infelizmente, fazer isso é um pouco mais prolixo. Requer o uso 
das anotações (Content e @Schema , na seguinte forma: 


import io.swagger.v3.0as.annotations.media.Content; 
import io.swagger.v3.0as.annotations.media.Schema; 


@GetMapping("/drivers/{id}") 


@Operation( 
description = "Localiza um motorista especifico", 
responses = { 
@ApiResponse(responseCode = "200", description = "Caso o mo 


torista tenha sido encontrado na base"), 
@ApiResponse(responseCode = "404", 
description = "Caso o motorista não tenha sido 
encontrado", 
content = @Content(schema = @Schema(implementa 
tion = ErrorResponse.class) ) 


) 


) 
public Driver findDriver( @PathVariable("id") Long id) {} 


O que agora gera: 
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252 


Code 


200 


400 


404 


Description 


Caso o motorista tenha sido encontrado na base 


Media type 
application/json v 


Controls Accept header. 


Example Value | Schema 


{ 
"id": 0, 


"name": “string”, 
“birthDate": "2020-02-29721:53:16.714Z" 





default response 


Media type 
*p v 


Example Value Schema 


{ 
"errors": [ 
{ 
"message": "string" 





Caso o motorista não tenha sido encontrado 


Media type 
application/json v 


Example Value Schema 


{ 


"errors": [ 


"message": "string" 





Figura 8.6: /drivers/{id} mapeado corretamente 
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Vamos incluir um mapeamento semelhante na classe 
DefaultErrorHandler , pois o Swagger não conseguiu detectar o 
tipo de conteúdo dos erros 400 . Vamos então incluir o 
mapeamento de forma similar ao do método findDriver , e 
deixar o método handleMethodArgumentNotValid assim: 


@ApiResponses( 
@ApiResponse(responseCode = "400", content = @Content( 
mediaType = "application/json", 


schema = @Schema(implementation = ErrorResponse.class) 


)) 


) 
public ErrorResponse handleMethodArgumentNotValid(MethodArgumentN 


otValidException ex) 
VA sãos 


Voltando a classe DriverAPI , podemos também mapear o 
parâmetro id do método, utilizando a anotação @Parameter : 


public Driver findDriver( 
@Parameter (description = "ID do motorista a ser localizado" 


@PathVariable("id") Long id) { 


return driverRepository.findById(id).orElseThrow(() -> new Res 
ponseStatusException(HttpStatus.NOT_FOUND) ); 


} 


Isso gera a documentação nesta forma: 


Name Description 

id * required 

integer ID do motorista a ser localizado 
(path) 


id - ID do motorista a ser localizado 


Figura 8.7: Documentação de parâmetros 
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Em casos de objetos mais complexos, devemos realizar o 
mapeamento das anotações diretamente nos objetos, utilizando a 
anotação (Schema vista anteriormente. Por exemplo, o objeto 
Driver fica assim: 

@Data 
@Entity 
@Schema(description = "Representa um motorista dentro da platafor 


ma") 
public class Driver { 


@Id 
@GeneratedValue 


Long id; 


@Schema(description = "Nome do motorista") 
String name; 


@Schema(description = "Data de nascimento do motorista") 
Date birthDate; 


Para visualizar o efeito desta alteração, vamos descer 
totalmente na página do Swagger, até a seção de Schemas : 
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Schemas 


ErrorData > 


ErrorResponse > 


Driver v { 
description: E 
Representa um motorista dentro da plataforma 
id integer ($int64) 
name string 
Nome do motorista 
birthDate string($date-time) 
Data de nascimento do motorista 


Figura 8.8: Schema da classe Driver 


Observe que o mapeamento é sensível a algumas anotações de 
validação, incluindo (size . Isso fará com que a validação do 
objeto (conforme visto no capítulo 7) também seja utilizada para 
efeitos de documentação. Vamos alterar a classe Driver para ver 
isso na prática: 

@Data 
@Entity 
@Schema(description = "Representa um motorista dentro da platafor 


ma") 
public class Driver { 


@Id 
@GeneratedValue 
Long id; 


@Schema(description = "Nome do motorista") 
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@Size(min=5, max = 255) 
String name; 


@Schema(description = "Data de nascimento do motorista") 
Date birthDate; 
; 
O resultado fica: 
Driver v { 
description: 
Representa um motorista dentro da plataforma 
id integer ($int64) 
name string 
maxLength: 255 
minLength: 5 
Nome do motorista 
birthDate string($date-time) 
Data de nascimento do motorista 
} 


Figura 8.9: Schema da classe Driver com restrições de tamanho 


O último ponto é acrescentar algumas informações sobre a 
documentação em si, como o nome da API, uma breve descrição, 
versão e informações de contato. Isso é feito através de um objeto 

OpenAPI , que nós inserimos no contexto do Spring através da 
estratégia de criação de configurações: 


package app.car.cap08.config; 


import io.swagger.v3.0as.models.OpenAPI; 

import i0.swagger.v3.oas.models.info.Contact; 

import io.swagger.v3.0as.models. info. Info; 

import org.springframework.context.annotation.Bean; 

import org.springframework.context.annotation.Configuration; 


(Configuration 
public class OpenAPIConfig { 


256 8.1 CRIANDO UMA DOCUMENTAÇÃO VIVA COM SWAGGER/OPENAPI 


@Bean 
public OpenAPI openAPIDocumentation() { 
return new OpenAPI() 
. info( 
new Info() 
.title("C.A.R. API") 
.description("API do sistema C.A.R., de facilitaçã 
o de mobilidade urbana") 
.version("v1.0") 
.contact (new Contact() 
.name( "Alexandre Saudate") 
.email("alesaudate@gmail.com") 


); 


O que reflete na documentação da seguinte forma: 


C.A.R. API P & 


iv3/api-docs 


API do sistema C.A.R., de facilitação de mobilidade urbana 


Contact Alexandre Saudate 


Figura 8.10: Cabeçalho da documentação com as novas informações 


A última ação a ser tomada é simplificar a classe DriverAPI . 
As novas anotações tomaram muito espaço e prejudicam a leitura 
da implementação - para isso, uma boa prática é criar uma 
interface e colocar as anotações de documentação nela. Desta 
forma, renomeamos a classe para DriverAPIImpl e criamos uma 
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nova interface chamada DriverAPI , com o seguinte corpo: 
package app.car.cap08. interfaces. incoming; 

// imports omitidos 

@Tag(name = "Driver API", description = "Manipula dados de motori 


Stass T) 
public interface DriverAPI { 


@Operation(description = "Lista todos os motoristas disponivei 
Sm) 
List<Driver> listDrivers() ; 


@Operation( 
description = "Localiza um motorista especifico", 
responses = { 
@ApiResponse(responseCode = "200", description = "Caso o 


motorista tenha sido encontrado na base"), 
@ApiResponse(responseCode = "404", 
description = "Caso o motorista não tenha s 
ido encontrado", 
content = @Content(schema = @Schema(impleme 
ntation = ErrorResponse.class) ) 


) 
) 


Driver findDriver( @Parameter(description = "ID do motorista a 
ser localizado") Long id) ; 


Driver createDriver( @Parameter(description = "Dados do motori 
sta a ser criado") Driver driver) ; 


Driver fullUpdateDriver(Long id, Driver driver); 
Driver incrementalUpdateDriver(Long id, Driver driver) ; 


void deleteDriver(Long id) ; 


Agora, podemos simplesmente retirar todas as anotações 
OpenAPI da classe DriverAPIImpl e fazer com que esta 
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implemente a interface DriverAPI . 


8.2 UTILIZANDO O DOCUMENTER DO 
POSTMAN 


Uma forma também muito utilizada pelos criadores de APIs 
como um todo é utilizar o próprio Postman para criar uma 
documentação acessível tanto para pessoal de negócios quanto 
para pessoal técnico. Esta forma de geração da documentação é um 
pouco menos efetiva do que a OpenAPI em termos de manter-se 
viva, já que depende do Postman (ou seja, uma ferramenta externa 
ao código) para que possa ser criada e atualizada. Entretanto, por 
ser uma ferramenta utilizada para se interagir de forma técnica 
com as APIs, essa desvantagem é parcialmente compensada. 


Já sua grande vantagem é manter acessível a documentação 
independente do código. O Postman possui uma forma de publicar 
a documentação e deixá-la disponível online, de forma que 
qualquer um que queira utilizar a API pode fazer isso com a 
documentação aberta. Ele ainda ajuda quem desenvolve 
mostrando como consumir cada API com várias linguagens 
disponíveis, compensando bastante a desvantagem de ser apartado 
do código. 


Vamos começar atualizando a documentação. Atualizei a 
coleção do Postman com todos os recursos que foram criados até 
agora e os separei por pastas: 


8.2 UTILIZANDO O DOCUMENTER DO POSTMAN 259 


APIs REST 


14 requests 


~ B® Motoristas aoa 
ser Listar motoristas 
sos Criar motorista 
ser Localizar um motorista específico 
eur Atualizar motorista 
DEL Apagar motorista 
PATCH Atualizar motorista (incremental) 
v Mm Requisições de viagens nee 
weer Criar requisição de viagem 
ser Recuperar requisições de viagens. 
v Ba Passageiros "sg 
ser Listar passageiros 
ves Criar passageiro 
ser Localizar passageiro específico 
pur Atualizar passageiro 
DEL Apagar passageiro 
parem Atualizar passageiro (incremental) 


Figura 8.11: Collection do Postman completa 


Ao clicar sobre o ícone de reticências da API, vejo uma série de 


opções: 
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PI + 
he APIs_REST 


lá requests +04 


v &@ Mo Share Collection 


a 
ser ll @& Manage Roles 


= 


Rename 
om tt XA edt 


3 Create a fork 


PATCH À EM Add Request 


C} Add Folder 
œ Cf Duplicate 
eR + Export 
v Mm Pat 4 Monitor Collemon 
ser LI æ Mock Collection 
m= U | publish Docs 
ser ll » Remove from workspace 


pur A Ti Delete 


DEL Apagar passageiro 


Figura 8.12: Menu dropdown da collection do Postman 


Para publicar a collection, clique no botão Publish Docs . Isso 
vai fazer com que o Postman envie esta collection para o site e abra 
uma tela no navegador para configuração de como esta 
documentação será exposta: 
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Publish collection Content 


Collection version 


CURRENT 


Emvironrent 


URL 


Custom domain 


Styäng 





Top Bar Color 


REFFFFF 


Right Sidebar Color 


#303030 w 


Migħlighe Color 


Collection discovery Disabied 


Expand your outreach by letting users discover this collection in explore postman corr 


Figura 8.13: Tela de publicação da documentação do Postman 


Esta tela permite que se configure (dentre outras coisas) a 
versão da collection a ser utilizada e o environment. O environment 
nada mais é do que uma coleção de atributos que pode ser utilizada 
para que possamos alternar de maneira rápida os ambientes que 
vamos utilizar. Por exemplo, suponha que o host dos serviços que 
utilizamos localmente seja localhost:8080 , e o de produção 
será api.car.com.br . Então podemos definir uma variável 

host no environment para que seja fácil de alternar entre estes 
dois ambientes. 


Vamos configurar um environment? Para isso, abra novamente 
o Postman e localize na parte superior à direita da tela um campo 
assim: 


262 8.2 UTILIZANDO O DOCUMENTER DO POSTMAN 





No Environment X o * 


=] Comments (0 Examples (0) + 


Figura 8.14: Definição do environment do Postman 


Clique no icone da engrenagem. Isso fara com que uma tela de 


gerenciamento de environments se abra: 





Learn more about environment 


Create an environmer 


Figura 8.15: Tela para criar novos environments 


Clique no botão Add . Vamos agora criar 
chamado local-secure e definir uma variável 
valor https://localhost: 8080 : 


um ambiente 
host , com o 
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MANAGE ENVIRONMENTS 





Add Environment 


local-secure 
VARIABLE INITIAL VALUE @ CURRENT VALUE O 
host httpsy/localhost:8080|  https://ocalhost:8080 


& Use variables to reuse values in different places. The current value is used while sending a request and is 


never synced to Postman's servers, The Initial value is auto-updated to reflect the current value, í 





his behaviour from Settings. Learn more about variable value 


Figura 8.16: Criação do environment local-secure 


Para utilizar essa variável, vamos abrir uma das requests 
( Listar motoristas , por exemplo) e inserir a variável na URL 
entre chaves, da seguinte forma: {{host}}/drivers . Note que o 
texto da variável fica vermelho se não houver nenhum 
environment no dropdown, e laranja se selecionarmos o 
environment local-secure que criamos: 
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Postman 


File Edit View Help 


New + ss MyWorkspace ~ & Invite GO 





local-secure v 
Post Criar pa PUT At PATCH Atualiza GET Lisi 





» Listar motoristas EM comments(0) Exam 


Utilizamos esta API para listar os motoristas que estão na base 





GET + — {{host)}/driverg 


Params Cor 


Query Params 


KEY VALUE DESCRIPTION 


Hit Send to get a response 


oH @& E Er Bootcamp Build Browse 





Figura 8.17: Utilizando a variável host 


Vamos voltar ao ponto onde estávamos anteriormente, 
clicando novamente no botão Publish Docs . Observe que agora 
aparece o environment local-secure para publicação. Deixe-o 
selecionado, como na figura: 


8.2 UTILIZANDO O DOCUMENTER DO POSTMAN 265 


Publish collection Content 


Collection version 


Content 
CURRENT ” 
URL 
Environment 
Styling 
local-secure X 
Collection Discovery 
URL 


© Preview Documentation . 
Custom domain 


No custom domain v 
Figura 8.18: Environment local-secure na publicação da documentação 
É possível visualizar um preview da documentação antes de 
efetivamente publicá-la (ou seja, torná-la publicamente acessível). 


Para isso, clique no botão Preview Documentation . Uma tela 
semelhante à seguinte se abrirá: 
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O s- ES 


ams mst 


vane APIs REST 





Motoristas 





Figura 8.19: Preview da documentação do Postman 


Observe que no canto direito da tela estão as requests para 
nossa API. Essa seção disponibiliza um dropdown com várias 
linguagens e frameworks. Trocar essas linguagens fará com que os 
códigos dos clientes adequados sejam gerados automaticamente, 
prontos para serem colados na sua IDE e para que você possa 
trabalhar com essa API diretamente! 


Um tipo particular dessas implementações, por exemplo, é o 
HTTP. Ao selecionar essa opção, você pode visualizar diretamente 
que tipo de informação é enviada para o servidor: 
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Listar motoristas 


GET /drivers HTTP) 


Host: http 


POST /drivers HITP/1 


Host: http 


Content-Type: application/json 





Figura 8.20: Trocando a linguagem do documenter 


O último ponto que resta agora é melhorar a documentação. 
Vamos tomar como exemplo apenas como documentar uma 
determinada API, como a de listar motoristas. Com ela aberta no 
Postman, clique na seta que aparece à esquerda do nome. Uma 
caixa de texto deve se abrir logo abaixo dela, com um botão escrito 
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Add a description . Clique nesse botão e insira um texto de 
documentação, conforme a figura: 


” Listar motoristas 


Utilizamos esta API para listar os motoristas que estão na base.| 


Figura 8.21: Incrementando a documentação 


Refaça o processo de publicação e preview para ver como ficou: 


Motoristas 


GET Listar motoristas 
http/drivers 


Utilizamos esta API para listar os motoristas que estão na base, 


Figura 8.22: Alteração aparecendo no documenter 


Quando estiver satisfeito com o resultado, clique no botão 
Publish Collection que fica no rodapé da página de edição de 
configurações. A API será publicada e uma tela semelhante à 
seguinte será vista: 
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Collection is published © Seats 


Content 
APIs. REST Versions: CURRE 


No Environment 


URL 


https;//documenter.getpostman.com/view/655669/S2KZtGr7 


Styling 
o 


Figura 8.23: Collection publicada 


Observe que o Postman gerou uma URL própria para a 
documentação, que agora está disponível na internet. 


Dica 


Esta API realmente esta publicada em 
https://documenter.getpostman.com/view/655669/SzKZtGr7. 
Você pode utilizá-la para testar todos os exemplos deste livro. 
Além disso, o arquivo contendo a coleção do Postman 
também está disponível (junto com todo o código-fonte deste 


livro) em https://github.com/alesaudate/rest-v2. 





Conclusão 


Neste capítulo, vimos duas formas diferentes de documentar 
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sua API. Uma delas, mais próxima de quem desenvolve (o 
OpenAPI). A outra, também próxima dos desenvolvedores mas 
buscando criar uma proximidade maior do pessoal de negócios. 
Ambas são formas muito boas de documentar e podem ser usadas 
concomitantemente (isto é, não é necessário escolher entre uma ou 
outra - você pode usar ambas). Para realizar a escolha, talvez seja 
interessante ter em mente qual será o público-alvo da 
documentação da API. 


O próprio processo de documentar, entretanto, é 
extremamente importante. Procure manter isso como uma prática 
constante, pois fará toda a diferença na evolução dela. 
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CaPiTULO 9 


OUTRAS TECNICAS 


"A educação é a arma mais poderosa que você pode usar para 
mudar o mundo." - Nelson Mandela 


Ao longo deste livro, as técnicas foram sendo abordadas 
conforme criávamos a API C.A.R.. Outras técnicas muito 
importantes, no entanto, não puderam ser abordadas a tempo, por 
distintas razões. Como algumas delas são demasiado importantes 
para ficarem de fora deste livro, este capítulo tem justamente a 
intenção de abordá-las e completar o assunto. Trata-se de um 
compilado de técnicas: em algumas, vou manter o meu estilo e 
mostrar junto com exemplos; para outras, vou apenas discorrer a 
respeito. 


9.1 PAGINAÇÃO 


Talvez a técnica mais importante que não foi abordada ao 
longo do livro seja a paginação. Esta é uma técnica extremamente 
importante para poupar recursos (em termos de memória, CPU, 
rede etc.). Consiste em "fatiar" o conteúdo de um determinado 
recurso e devolver ao cliente da API somente a fatia solicitada. 
Quando isso é feito, o cliente lida apenas com o conteúdo que 
realmente importa - se ele tivesse uma grande massa em mãos 
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imediatamente, fatalmente ele teria que desprezar algo. Isso geraria 
desperdício dos recursos já mencionados. O objetivo, portanto, é 
minimizar esse desperdício. 


Antes de começar, no entanto, deixo um alerta: o Spring é uma 
ferramenta muito completa, e apresenta recursos para realizar 
várias tarefas e de diferentes formas. A forma que eu vou 
apresentar a seguir foi balanceada para atender aos critérios da 
interoperabilidade entre os frameworks utilizados, de modo mais 
RESTful possível e também para facilitar a servir HATEOAS. 


Vamos primeiro analisar do que vamos precisar. A paginação 
consiste de uma filtragem de recursos, por isso faz sentido que seja 
aplicada somente sobre a URL de listar vários recursos. Vamos 
utilizar a API de listagem de motoristas para verificar isso. 


Sendo uma filtragem, vamos utilizar query parameters para 
fazer isso. O cliente terá a possibilidade de enviar o número da 
página desejada. Em um primeiro momento, vamos deixar 
hardcoded o tamanho da página em 20 registros, sendo que isso 
será facilmente substituível. 


O primeiro passo é normalizar o nome da URL. Este é um 
débito técnico que deixamos quando realizamos a criação da API 
de motoristas. Para isso, vamos retirar o trecho /drivers de 
todos os mapeamentos da classe e transferi-lo para a anotação 
@RequestMapping que está na declaração da classe diretamente. 
Nosso código fica assim: 

@RequestMapping(path = "/drivers", produces = MediaType.APPLICATI 


ON_JSON_VALUE) 
public class DriverAPIImpl implements DriverAPI { 


@GetMapping 
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public List<Driver> listDrivers() { 
(A ave 


} 


@GetMapping("/{id}") 
public Driver findDriver( @PathVariable("id") Long id) { 
hare 


} 


@PostMapping 
public Driver createDriver(@RequestBody Driver driver) { 
PA uii 


} 


@PutMapping("/{id}") 
public Driver fullUpdateDriver(@PathVariable("id") Long id, @R 
equestBody Driver driver) { 
P ree 


} 


@PatchMapping("/{id}") 
public Driver incrementalUpdateDriver (@PathVariable("id") Long 
id, @RequestBody Driver driver) { 
(re 


3 


@DeleteMapping("/{id}") 
public void deleteDriver(@PathVariable("id") Long id) { 
a eee 


} 


Agora, vamos alterar o método listDrivers para receber 
como parâmetro o número da página. Como não queremos forçar 
o cliente a fornecer este valor, vamos fazer com que ele seja 
opcional, com valor padrão sendo 0. Vamos também criar uma 
constante para delimitar o número de registros em cada página (no 
caso, 10): 


private static final int PAGE SIZE = 10; 


@GetMapping 
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public List<Driver> listDrivers(@RequestParam(name = "page", defa 
ultValue = "0") int page) { 

TI seats 
} 


Para utilizar a paginação, vamos utilizar um método presente 
no nosso repositório. Este método é o findAl1, que recebe como 
parâmetro uma instância de Pageable . Podemos criar esta 
instância utilizando o método of da classe PageRequest : 


import org.springframework. data. domain.Page; 
import org.springframework. data. domain. PageRequest; 


THe decano 


@GetMapping 
public List<Driver> listDrivers(@RequestParam(name = "page", defa 
ultValue = "0") int page) { 

Page<Driver> driverPage = driverRepository.findAll(PageRequest 
.of (page, PAGE SIZE)); 

return driverPage.getContent(); 


} 


Por si só, a paginação já está pronta. Para testar, vamos subir a 
aplicação e abrir o Swagger: 
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O swagger UI 


€ > © A Notsecure | localhost:8080/swagger-ui/index.html?configUrl=/v3/api-docs/swagger-config#. w @ incognito 








| ser | /drivers | Signin 
| 


| https://localhost:8080 


Lista todos os motoristas disponi 
| Username || 
| 


Password 





Parameters 


| 
Name Description | 


page * reuni 
integer 
(query) 





0 


Responses 


Description Links 


No links 
default response 











Figura 9.1: Apenas não esqueça de se autenticar quando testar 


Ao receber a resposta de uma primeira requisição, notamos 
que o resultado vem vazio. Assim sendo, precisamos popular o 
sistema com dados suficientes (mais de 10 motoristas) para que 
possamos ver a paginação em ação. Uma vez populado, 
verificamos que, quando passamos como parâmetro a página 0, 
um retorno de no máximo 10 motoristas vem como resultado. Ao 
passar como parâmetro a página 1, recebemos um único motorista, 
ou seja, justamente o que faltava na página 0. 


Há um porém. Vamos observar o resultado da página 1: 
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"id": 12, 
"name": "motoristaii", 
"birthDate": "2020-03-05T17:18:04.558+0000" 


Observe que não ha informações presentes sobre se esta é a 
última página, ou qual o endereço da página anterior. Daí, 
podemos perceber que o uso de HATEOAS traria um grande 
benefício para essa paginação. Vamos então refatorar a classe 
listDrivers para estar adequada aos links HATEOAS. 


A primeira coisa a ser feita é trocar a classe de retorno do 
método para a classe CollectionModel . Esta classe é semelhante 
à EntityModel que vimos no capítulo 3, mas especializada para 
funcionar com coleções. Para utilizá-la, vamos usar o construtor 
dela que recebe uma lista: 


import org.springframework.hateoas.CollectionModel; 
// 


@GetMapping 
public CollectionModel<Driver> listDrivers(@RequestParam(name = " 
page", defaultValue = "0") int page) { 

Page<Driver> driverPage = driverRepository.findAll(PageRequest 
.of (page, PAGE SIZE)); 

CollectionModel<Driver> collectionModel = new CollectionModel< 
>(driverPage.getContent()); 

return collectionModel; 


O próximo passo é adicionar os links de fato. Para isso, vamos 
importar estaticamente os métodos presentes na classe 
WebMvcLinkBuilder , que vão nos ajudar a construir os links que 
queremos. Como temos que referenciar recursivamente o recurso 
/drivers , apenas modificando o valor do query param page, 
vamos usar primeiro o método methodon . Ele é um tanto quanto 
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peculiar, pois passamos como parametro a classe do controlador 
usado (no caso, a própria DriverAPIImp1 ), e depois chamamos o 
método que será responsável por prover o que se espera deste link. 


Para elaborar esta chamada, vamos imaginar com qual 
parâmetro o método listDrivers deve ser chamado para que 
seja a última página. Não temos acesso direto a este dado, mas 
temos como calcular. Acontece que a classe Page disponibiliza 
um método chamado getTotalPages , que retorna o número 
total de páginas. Ou seja, se tivermos uma única página, este 
método retornará 1 - que será referente à página de número 0. No 
nosso caso, como temos duas páginas de dados, a última página é a 
de número 1 - e o método getTotalPages retorna 2. Assim 
sendo, para calcular qual é a última página, utilizamos o método 

getTotalPages e subtraímos 1. 


O código (parcial) fica assim: 


import static org.springframework.hateoas.server.mvc.wWebMvcLinkBu 
ilder.*; 
TL ca cai 


@GetMapping 
public CollectionModel<Driver> listDrivers(@RequestParam(name = " 
page", defaultValue = "0") int page) { 

Page<Driver> driverPage = driverRepository.findAll(PageRequest 
.of (page, PAGE SIZE)); 

CollectionModel<Driver> collectionModel = new CollectionModel< 
>(driverPage.getContent()); 


methodon(DriverAPIImpl.class).listDrivers(driverPage.getTotalP 
ages() - 1); 


return collectionModel; 


Por último, vamos criar o método de fato para esta chamada. 
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Vamos encapsular a chamada ao método JlistDrivers no 
método linkTo (que foi importado estaticamente), e em seguida 
acrescentar o rel lastPage no link. Por último, vamos 
acrescentar este link no CollectionModel : 


import org.springframework.hateoas.Link; 
Li hah 


@GetMapping 
public CollectionModel<Driver> listDrivers(@RequestParam(name = " 
page", defaultValue = "0") int page) { 

Page<Driver> driverPage = driverRepository.findAll(PageRequest 
.of(page, PAGE SIZE)); 

CollectionModel<Driver> collectionModel = new CollectionModel< 
>(driverPage.getContent()); 


Link lastPageLink = linkTo(methodOn(DriverAPIImpl.class).listD 
rivers(driverPage.getTotalPages() - 1)) 


-withRel("lastPage"); 


return collectionModel.add(lastPageLink) ; 


} 
Agora, ao realizar o teste, obtemos algo como: 
{ 
"embedded": { 
"driverList": [ 
{ 
"id"? 2, 
"name": "motoristai", 
"birthDate": "2020-03-05T18:09:12.017+0000" 
x 
// Vários outros motoristas... 
] 
+, 
" links": { 
"lastPage": { 
"href": "https://localhost:8080/drivers?page=1" 
} 
3 
} 
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Observe a presença do atributo _embedded antes da lista de 
motoristas. Este é um artifício utilizado pelo Spring HATEOAS 
para ser aderente à especificação Hypertext Application 
Language (HAL), (conforme KELLY, 2013). Trata-se de uma 
especificação de um formato JSON onde a hipermídia é auto- 
orientada, de acordo com os preceitos da tese de Roy Fielding. Ao 
utilizar algumas das features do HAL, o usuário seria auto- 
orientado a seguir os links para prover a funcionalidade de negócio 
desejada. 


O uso do HAL pode trazer vantagens e desvantagens. 
Enquanto é notório que seguir uma especificação traz benefícios 
na padronização e faz com que sua API seja autodescrita e 
autodocumentada, ela pode trazer complicações no consumo, já 
que nem todos os clientes podem querer navegar dentro de um 
atributo com um nome enigmático como _embedded 
Infelizmente, retirar este atributo usando a propria API do Spring 
pode ser um tanto problematico. Ao questionar o time de 
manutenção do Spring HATEOAS (conforme visto na thread do 
GitHub https://github.com/spring-projects/spring- 
hateoas/issues/1214 - que por sua vez levou a resposta no Stack 
Overflow disponivel em 
https://stackoverflow.com/a/60609135/1748132), obtive algumas 
respostas que mostram apenas que o caminho para remover este 
atributo é criando sua propria classe de mapeamento. 


Assim sendo, vamos criar uma classe chamada Drivers onde 
vamos incluir dois atributos: um chamado drivers (que vai ser 
uma lista de EntityModel<Driver> ) e outro chamado links 
(que vai ser uma array do tipo Link ). Observe que não 
precisamos de uma classe muito mais complexa do que isso, de 
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forma que vamos apenas criá-la com um construtor aceitando os 
campos como parâmetro e os devidos getters. O código completo 
da classe fica assim: 


package app.car.cap09. interfaces. incoming.output; 


import app.car.cap09.domain.Driver; 

import lombok.Getter; 

import org.springframework.hateoas.EntityModel; 
import org.springframework.hateoas. Link; 

import java.util.List; 


@Getter 
public class Drivers{ 


private List<EntityModel<Driver>> drivers; 
private Link[] links; 


public Drivers(List<EntityModel<Driver>> content, Link... lin 


ks) { 


this.drivers = content; 
this.links = links; 


Vamos agora reescrever o código do método listDrivers 
com as mudanças - tanto com o "envelopamento" dos objetos 
Driver dentro de instâncias EntityModel quanto com a adoção 
da classe Drivers . O código fica assim: 
@GetMapping 
public Drivers listDrivers(@RequestParam(name = "page", defaultVa 
lue = "0") int page) { 


Page<Driver> driverPage = driverRepository.findAll(PageRequest 
.of(page, PAGE SIZE)); 


List<EntityModel<Driver>> driverList = new ArrayList<>(); 


for (Driver driver : driverPage.getContent()) { 
driverList.add(new EntityModel<>(driver)); 
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Link lastPageLink = linkTo(methodOn(DriverAPIImpl.class).listD 
rivers(driverPage.getTotalPages() - 1)) 
-withRel("lastPage"); 


return new Drivers(driverList, lastPageLink); 


J 
Finalmente, obtemos o seguinte resultado: 
{ 
"drivers": [ 
{ 
"idi 2, 
"name": "string", 
"birthDate": null, 
"links": [] 
Er 
í 
"idi 3; 
"name": "string", 
"birthDate": null, 
"links": [] 
} 
1, 
"links": [ 
{ 
"rel": "lastPage", 
"href": "https://localhost :8080/drivers?page=0" 
} 
] 
} 
9.2 CORS 


Uma técnica muito importante que deve ser conhecida por 
desenvolvedores de APIs é a CORS. Trata-se da sigla para Cross- 
Origin Resource Sharing (ou, segundo a tradução da Mozilla 
disponível em https://developer.mozilla.org/pt- 
BR/docs/Web/HTTP/Controle_Acesso_CORS, 
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Compartilhamento de recursos com origens diferentes ). 
Trata-se de uma técnica originada a partir de uma necessidade de 
segurança. Vamos ver como isso funciona: 


Suponha uma API disponível em um servidor (hipotético) 
https://api.car.com.br . Suponha também uma aplicação 
JavaScript sendo executada em https://bestcars.com tentando 
acessar a API. A menos que devidamente instruído, todo browser 
moderno impede este acesso, por conta de um problema de 
segurança. Este problema consiste do seguinte: imagine que 
https://bestcars.com foi hackeado. Os hackers modificaram o 
código do site para usar a máquina do cliente como um zumbi, e 
utilizá-la em um ataque DDoS ( Distributed Denial of 
Service ) sem que o usuário saiba. Para evitar este (e outros) 
cenários, foi criada a técnica CORS. 


A técnica consiste em realizar a liberação do acesso externo 
apenas para domínios que são conhecidos. Por exemplo, se 
https://bestcars.com tentar acessar 
https://api.car.com.br , este acesso será bloqueado a menos 
que a API da cars responda de maneira adequada ao 
procedimento CORS . É uma pequena negociação, que vou explicar 
com detalhes a seguir. 


O cliente JavaScript é instanciado pelo browser. Isso faz com 
que este cliente já conheça as regras de CORS e faça 
automaticamente o procedimento. Primeiro, este envia uma 
requisição com o método HTTP OPTIONS , que tem a função de 
nao retornar nenhum corpo no resultado, somente alguns 
cabecalhos de controle que mostram quais métodos HTTP podem 
ser executados sobre aquela URL. Utilizando a nossa API de 
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motoristas como exemplo, se existir um motorista de ID 1 e o 
método OPTIONS for executado sobre /drivers/1 , então sera 
informado que os métodos GET , PUT, PATCH e DELETE estão 
disponíveis (além dos métodos HEAD e OPTIONS ). 


Se a execução do método OPTIONS for parte de uma 
negociação CORS, o browser também enviará na requisição qual a 
origem dela, isto é, a partir de qual domínio está partindo a 
requisição HTTP. Além disso, o browser envia o método que tem a 
intenção de executar e quais cabeçalhos (se houver cabeçalhos 
além daqueles que a especificação CORS permite). O servidor 
responderá com um código de status 200 se a requisição for aceita 
e 403 caso contrário. 


O METODO OPTIONS só É usano EM CORS? 


Em realidade, o método OPTIONS foi criado com o intuito de 
guiar o cliente a respeito da maneira como navegar em uma 
URL, isto é, apresentando quais métodos HTTP podem ser 
executados sobre ela. A partir da necessidade de uso da 


técnica CORS é que o OPTIONS evoluiu para tratar estas 


questões de apresentar outras opções disponíveis. 





Para habilitar CORS no nosso projeto, precisamos modificar as 
configurações do Spring Security. Caso o Spring Security não 
esteja implementado no seu projeto, consulte a documentação 
oficial a respeito de como realizar a configuração. 


No método configure da classe SecurityConfig , logo 


284 9.2 CORS 


abaixo da declaração onde estamos desabilitando o CSRF, vamos 

incluir uma chamada ao método cors() . Este método vai 

inicializar a configuração para nós: 

@Override 

protected void configure(HttpSecurity http) throws Exception { 
http.csrf().disable(); 


http.cors(); 
// restante do método 


Vamos também incluir um bean chamado 
CorsConfigurationSource . Este bean é utilizado para "amarrar" 
a configuração do CORS da aplicação com as URLs sobre as quais 
a configuração é válida. Para declarar quais origens, métodos 
HTTP e cabeçalhos são aceitos, utilizamos a classe 
CorsConfiguration . Para realizar este controle, utilizamos os 
métodos setAllowedOrigins , setAllowedMethods e 
addAllowedHeader , respectivamente. A declaração é feita assim: 


import org.springframework.web.cors.CorsConfiguration; 
import org.springframework.web.cors.CorsConfigurationSource; 


@Bean 
public CorsConfigurationSource corsConfigurationSource() { 


CorsConfiguration configuration = new CorsConfiguration(); 

configuration.setAllowedOrigins(Arrays.asList("https://bestcar 
s.com")); 

configuration. setAllowedMethods(Arrays.asList("GET","POST", "P 
UT", "DELETE", “PATCH"):); 

configuration.addAllowedHeader("*"); 


// 


Note que, ao utilizar * no método addAllowedHeader , 
estamos declarando que todos os cabeçalhos são permitidos. O 
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mesmo é suportado nas outras declarações (ou seja, indicando que 
qualquer origem de dados e qualquer método HTTP são 
permitidos), embora isto não seja recomendado, já que o CORS 
existe por motivos de segurança. 


Finalmente, para declarar quais URLs da nossa API vão estar 
com essa configuração habilitada, vamos utilizar a classe 
UrlBasedcorsConfigurationSource . Esta classe vincula uma 
URL, ou padrão de URL, a uma configuração CORS. Para realizar 
este vínculo, utilizamos o método registerCorsConfiguration , 
passando como parâmetro o padrão /** (que vai interceptar 
todas as URLs) e a configuração que criamos anteriormente. Vale 
observar que a classe UrlBasedCorsConfigurationSource 
implementa a interface CorsConfigurationSource , ou seja, 
podemos retornar esta implementação no nosso método: 


import org.springframework.web.cors.CorsConfiguration; 

import org.springframework.web.cors.CorsConfigurationSource; 
import org.springframework.web.cors.UrlBasedCorsConfigurationSour 
ce; 


@Bean 
public CorsConfigurationSource corsConfigurationSource( ) 
{ 
CorsConfiguration configuration = new CorsConfiguration(); 
configuration.setAllowedOrigins(Arrays.asList("https://bestcar 
s.com")); 
configuration. setAllowedMethods(Arrays.asList("GET","POST", "P 
UT", "DELETE", "PATCH")); 
configuration.addAllowedHeader("*"); 
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfi 
gurationSource(); 
source.registerCorsConfiguration("/**", configuration); 
return source; 


Vamos agora testar como ficou a nossa configuração. Vamos 
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utilizar o método POST em “/drivers para verificar o 
funcionamento do CORS no nosso ambiente e fazer, inicialmente, 
três testes. O primeiro, para verificar como a API se comporta sem 
que utilizemos qualquer dos recursos de que CORS necessita para 
funcionar. No segundo, vamos utilizar o cabeçalho Origin para 
informar ao servidor qual é a origem de dados e verificar qual é a 
resposta, mas informando uma origem que não está na 
configuração que criamos. No último teste, vamos informar a 
origem https://bestcars.com (que foi a registrada na 
configuração do CORS) e verificar como o sistema se comporta. 


Vamos ao primeiro teste: 


Postman 
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Pretty Raw Preview Visualize SON + 5 
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Figura 9.2: Requisição sem o cabeçalho Origin 
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Como se pode observar, a API se comporta da maneira 
normal. Este é um comportamento que tem como público-alvo 
clientes que não precisam de CORS, ou seja, que nao são aplicações 
JavaScript. Desta forma, a API continua se comportando como se 
não houvesse configuração de CORS ajustada. Um lembrete: o 
próprio browser ajusta o cabeçalho Origin nas requisições, 
informando a origem. 


Se fizermos a mesma requisição, mas ajustando o cabeçalho 
Origin com um domínio desconhecido do servidor: 


Postman 
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Body Cookies Headers (12) Test Results tus; 403 Forbidden ne: 538ms Size; 447 B 
Pretty Raw Preview Visualize Text v = 
1 Invalid CORS request 
EI 4 [Ea Er Bootcamp Butid Brows) 


Figura 9.3: Requisição com o cabeçalho Origin numa origem não cadastrada 


Recebemos uma resposta com o código 403 e um texto dizendo 
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"Invalid CORS request" (requisição CORS inválida). 


Vamos então realizar a requisição com o cabeçalho Origin 
ajustado para https://bestcars.com , como foi configurado: 


Postman 


File Edit View Help 











New ~» n Runne HH My Wo e &, Invite G ("F oe wa 
local-secure 
por Criar motorista e OPT Lista cõe: > + ee 
+ Criar motorista EM comments o 
asa É aokii 
Params Authorization @ Headers (12) Body @ Pre-request Script Tests Settings 
Headers 
KEY VALUE DESCRIPTION eau Bu 
Content-Type application/json 
Origin https://bestcars.com 
Body € Headers (14) Test Results j 2000K Time; 97ms Size; 544B 
Pretty Raw Preview Visualize SON = = 
14 
2 e E 
3 "name": "string", 
4 "birthDate": null 
5 b 
E] =] tr Bootcamp Buile Browse 


Figura 9.4: Requisição com o cabeçalho Origin ajustado em https://bestcars.com 


Vemos que tudo transcorre normalmente desta forma. Temos 
certeza de que nossa configuração CORS está se comportando de 
acordo com a maneira esperada e rejeitando corretamente 
requisições inválidas. Mas quando as requisições são feitas por 
clientes JavaScript hospedados em browsers, existe um passo 
executado anteriormente. Este passo consiste em verificar se a 
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origem dos dados é aceita e quais métodos HTTP e cabeçalhos são 
suportados pela API. O servidor retorna estes dados como uma 
lista, de forma que o cliente pode deixar o resultado armazenado 
em cache e não realizar a mesma requisição várias vezes. 


Esta requisição consiste no uso do método HTTP OPTIONS, 
conforme explicado anteriormente. Quando executado fora de um 
contexto CORS, esse método tem a função de orientar o cliente 
sobre quais métodos HTTP estão disponíveis para execução na 
URL informada. No contexto CORS, os cabeçalhos Origin, 

Access-Control-Request -Method e Access-Control- 
Request -Headers também são utilizados para informar, 
respectivamente, se a origem informada está disponível, além de 
quais métodos HTTP e cabeçalhos. 
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Por QUE UMA REQUISIÇÃO É ENVIADA ANTES DA REQUISIÇÃO "DE 
VERDADE"? Isso NAO É UM DESPERDÍCIO DE RECURSOS? 


A requisição que é feita pelo CORS usando o método 

OPTIONS é chamada de requisição preflight. Ela não é 
enviada sempre pelo browser - existem condições específicas 
em que o browser considera ser seguro enviar a requisição 
para a API sem realizar essa negociação. Não pretendo listar 
aqui quais são essas condições, mas posso resumi-las como 
condições que remetem à navegação em páginas web, e não 
ao consumo de APIs REST. Quando estamos falando de uma 


API REST, o browser prefere mandar o preflight por ser uma 


forma de, teoricamente, utilizar um método que não gera 
quaisquer efeitos colaterais antes de realizar a requisição - 
que, por sua vez, pode gerar. Desta forma, o preflight é 
necessário como um meio de proteção contra efeitos 
colaterais. 





Vamos verificar isso em funcionamento. Execute o método 
OPTIONS sobre a URL /drivers , passando o cabeçalho 
Origin com https://bestcars.com , Access-Control- 
Request-Method com POST e Access-Control-Request- 
Headers com um cabeçalho qualquer (utilizei no exemplo x- 
custom-header ). Observe que, como configuramos * no 
servidor para os cabeçalhos, então todos são aceitos. Esta 
requisição retorna da seguinte forma: 
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Postman 


e Edit View Help 


ae MyW | é, Invite G a oe on r Upgrade ~ 











local-secure + og 
+ eee 
+ Listar opções EM comments n Examples 0 + 
OPTIONS = — (thost)/drivers Save v 
Params Authorization @ Headers (11) Body Pre-request Script Tests Settings 
Header 
KEY VALUE DESCRIPTION eee Ik Ed Presets + 
Origin https://bestcars.com 
Access-Control-Request-Method POST 
Access-Control-Request-Headers x-custom-header 
Body Cookies Headers (15) Test Results tatus: 2000K Time: 7ms Size: 566B Save Response v 
KEY 
Vary 
Vary 


Access-Control-Request-Method 


Access-Control-Request-Headers 





antrol-Allow-Origin 





ontrol-Allow-Methods UT,DELETE,PATCH 


x-custom-header 











nosniff 
X-XSS-Protection 1; mo 
Cache-Contro! ne , no-store, max-age=0, must-revalidate 
Pragma no-cache 
Expires 0 
Strict-Transport-Security max-age=31536000 ; includeSubDomains 
¥-Frama.Antiane DENY 
mae & Bootamp a Grows i 





Figura 9.5: Execução do método OPTIONS com todos os valores válidos 


Observe que, dentre os (muitos) cabeçalhos retornados, temos 

o Access -Control-Allow-Methods com 
GET, POST, PUT, DELETE, PATCH e o Access-Control-Allow- 
Headers com x-custom-header (o servidor não informa que 
todos os cabeçalhos são aceitos). Além disso, o código de status 
200 indica que a requisição POST com o cabeçalho citado pode ser 
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feita a partir dessa origem. 


Vamos checar o que acontece se trocarmos a origem: 


Postman 


aa My Workspace + & Invite O a O r Upgrade 









local-secure v o 
opr Listar opções o + ce % 
+ Listar opções EM comments n Examples 0 + 
as as Fo ERES ee 
Params Authorization @ Headers (11) Body Pre-request Script Tests Settings 
Headers 
KEY VALUE DESCRIPTION ees Ik Ed Presets + 
= origin https://domain.com x 
ntrol-Request-Method POST 
ntrol-Request-He: x-custom-header 
Body Cookies Headers (12) Test Results Status: 403 Fordidder Time: 537ms E 4476 Save Response v 
KEY VALUE 
Vary Origin 
Vary Access-Control-Request-Method 


Access-Control-Request-Headers 





pe-Options nosniff 








X-XSS-Protection 1; mode=block 

Cache-Control no-cache, no-store, max-age=0, must-revalidate 
Pragma no-cache 

Expires 0 


Strict-Transport-Sec 





max-age=31536000 ; includeSubDomains 





X-Frame-Options DENY 
Transfer-Encoding chunked 
Date Sat, 28 Mar 2020 20:24:44 GMT 
mama Er Bootcamp BL Browse E im 





Figura 9.6: Execução do método OPTIONS com uma origem inválida 


Da mesma forma que ocorreu com o método POST executado, 
o código de status também mudou para 403, ou seja, esta 
requisição não será aceita. 
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Por ultimo, vamos 


voltar 


a origem para 


https://bestcars.com e informar um método que não é aceito 


- digamos, o método HEAD : 


Postman 


File Edit View 


Help 


EE My Workspace » 








opr Listar 0) a + 
+ Listar opções 
OPTIONS = Jlhosydrivers 
Params Authorization @ Headers (11) Body 
Headers 

KEY VALUE 


Origin https://bestcars.com 


Hl 


<< | 





ntrol-Request-Method HEAD 





Headers (12) Tesi 





KEY 
Vary 
Vary 
vary 


X-Content-Type-Options 





Protection 


Cache-Control 





Expires 





ransport-Security 
X-Frame-Options 
Transfer-Encoding 


Date 





& Invite G a oe Mo. Upgrade 





local-secure há o 
E comments 1 Examples 0 + 
x Save * 

Tes Settings Cook f 
DESCRIPTION eum Ik Ed Presets + 


403 Forbidden Tim 


4478 


11ms Save Response v 
VALUE 

Origin 

Access-Control-Request-Method 

Access-Control-Request-Headers 


nosniff 





-store, max must-revalidate 








O ; includeSubDomains 
DENY 
chunked 


Sat, 28 Mar 2020 20:25:26 GMT 


7 Bootcamp BL Browse 


Figura 9.7: Execução do método OPTIONS com um método HTTP inválido 


Mais uma vez, recebemos o código de status 403. 
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9.3 OAUTH 


OAuth é a especificação de uma técnica de autenticação que 
permite que um site trabalhe com dados que venham de outro site 
- sem que seja necessário fornecer a senha do usuário final. Isso 
abre possibilidades para operações que hoje são bastante comuns, 
como realizar o cadastro em um site utilizando as credenciais de 
uma rede social, por exemplo. 


Quando a especificação surgiu (OAuth 1), utilizou-se à época 
uma analogia com carros de luxo e o modo valet (presente no 
Chevrolet Corvette C4 ZR-1, por exemplo). Funciona da seguinte 
forma: depois de criar várias APIs para o sistema da sua startup, 
você decide comprar um carro de luxo, muito potente, com cerca 
de 700 cv de motor. Então você decide pegar esse carro e ir a um 
restaurante badalado da cidade, onde o manobrista vai recebê-lo. E 
é aí que você se depara com a cena. Você. Deixando. A chave. Na 
mão. Do manobrista. Que você não conhece. Cujas intenções você 
não conhece. Cena aterradora de se pensar. Aliás, se você assistiu 
Curtindo a Vida Adoidado, você já pensou. 


Daí vem a ideia de se criar uma segunda chave para o carro. 
Uma que, quando inserida no carro, corta a potência do motor 
pela metade, não permite que se abra o porta-malas e dá 
autonomia para que se ande apenas por poucos quilômetros com o 
carro. 


O protocolo OAuth seguia com essa mesma noção. O carro 
seriam seus dados. Você continua sendo você. Seu usuário e senha 
são a chave para acesso dos dados. E o site interessado em acessar 
seus dados é o manobrista. O protocolo OAuth implanta a noção 
de se ter um token especial para o site para que seja possível 
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acessar somente aquilo de que ele necessita, sem ter que fornecer o 
usuário e senha. Como "bônus" esse token é revogável, ou seja, 
você tem total controle do que vai ser acessado pelo site e pode 
remover esse acesso quando achar melhor. 


A versão atual do OAuth é a 2. Algumas coisas mudaram entre 
as especificações, sendo que elas não são retrocompatíveis e até 
mesmo algumas nomenclaturas foram modificadas. Para conhecer 
o fluxo, vamos conhecer a nomenclatura dos envolvidos no 
processo: 


e Dono do recurso - geralmente, é você. 

e Cliente - é a aplicação interessada em acessar o recurso. 

e Servidor de recursos - é a aplicação onde o recurso (ou 
dados) está hospedado. 

e Servidor de autorização - é o servidor que cria a 
verificação de acordo com o protocolo OAuth. Na maioria 
das vezes, está junto do servidor de recursos. 


Para que um fluxo do OAuth funcione, uma série de etapas 
precisam ser concluídas. Para simplificar, vamos imaginar que 
você deseja disponibilizar para os usuários do sistema C.A.R. login 
utilizando dados de uma rede social qualquer (digamos, alguma 
que tenha um logotipo azul e branco). Estas etapas, de forma 
simplificada, são as seguintes: 


1) O usuário manifesta, ao clicar no botão de login do C.A.R., 
seu desejo em utilizar seus dados da rede social; 2) O C.A.R. (que já 
estava cadastrado na rede social e, portanto, possui um client 
ID eum client secret ) notifica a rede social deste desejo, e 
apresenta seus dados para a rede social; 3) A rede social devolve 
um link para que o usuário seja redirecionado; 4) O usuário, ao ser 
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redirecionado, se depara com uma tela expressando 0 uso que o 
C.A.R. fara de seus dados. Ao concordar, a rede social redireciona 
o usuário para o C.A.R. com um código de acesso; 5) De posse 
desse código de acesso, o C.A.R. faz uma nova requisição para a 
rede social, solicitando o access token que permite que o C.A.R. 
acesse o conjunto de dados que foi autorizado pelo cliente. 


Faço uma observação importante aqui: o fluxo mencionado 
acima precisa de um browser. E ele é apenas um dos fluxos 
disponíveis no OAuth 2. Na época do OAuth 1, havia só um fluxo 
possível (similar ao descrito acima, porém com alguns detalhes 
técnicos implícitos). O OAuth 2 veio para trazer mais 
pragmatismo à especificação e acrescentar vários fluxos diferentes, 
de acordo com a necessidade, tornando possível inclusive que APIs 
REST usem OAuth sem browser. Alguns dos fluxos disponíveis são 
os seguintes: 


e Authorization Code Flow 
e Client Credentials Flow 

e Device Flow 

e Password Credentials Flow 


Vamos revisá-los e verificar quando usar cada um. 


Authorization Code Flow 


Este fluxo é o mais semelhante ao OAuth 1, e é representado 
pelo passo a passo dado acima. Foi criado com a intenção de ser 
utilizado quando o cliente é uma aplicação web, em que o usuário 
utiliza um browser para fazer acesso. 


Quando o usuário utiliza alguma espécie de recurso que ativa a 
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necessidade do OAuth, o cliente o redireciona para o servidor de 
autorização para realizar o processo de consentimento, que 
consiste de revisar uma lista de informações para as quais o cliente 
terá acesso e um formulário de login. Quando o usuário faz login, 
ele está dando o consentimento para que o cliente execute as ações 
que precisa sobre os dados listados. 


Então, o servidor de autorização redirecionará o usuário para o 
sistema do cliente, portando um código de autorização (ou 
authorization code, que é o nome do fluxo). O cliente recebe esse 
código de autorização e o troca no servidor de autorização por um 
access token. Esse token é utilizado em todas as chamadas que serão 
feitas para o servidor de recursos, que os fornecerá, pois o token 
concede esse acesso ao cliente. 


Client Credentials Flow 


Este fluxo é mais semelhante a um fluxo de usuário/senha 
convencional, com a diferença de que tem seu público-alvo em 
aplicações. Ou seja, o seu uso tem a intenção de permitir que uma 
aplicação faça login em outra aplicação, sem necessariamente 
utilizar usuário e senha de uma pessoa, ou alguma senha 
“inventada”. Seu uso não é muito diferente de um fluxo intuitivo de 
usuário e senha: 


1. O cliente (aplicação) envia um par client ID e client 
secret para o servidor de autorização; 

2. O servidor de autorização valida e, caso estejam corretos, 
retorna um access token para o cliente; 

3. O ciente então vai até o servidor de recursos utilizando o 
access token, e tem acesso aos seus dados. 
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Device Flow 


Este fluxo procura focar na necessidade de dispositivos que 
tenha acesso limitado à internet e, portanto, talvez ofereçam uma 
experiência de uso pobre para seus usuários. Focando nesse 
detalhe, o fluxo procura oferecer um link de onde o usuário 
consiga continuar de onde parou. 


Por exemplo: ele inicia o processo em um celular, continua do 
computador e, quando volta para o celular, todo o fluxo está 
finalizado. Este fluxo, portanto, tem três estágios, cujas etapas são 
as seguintes: 


1. O usuário utiliza seu dispositivo móvel para requisitar os 
dados; 

2. O dispositivo envia uma requisição para o servidor de 
autorização; 

3. O servidor retorna o Device Code (ID do dispositivo 
registrado no servidor), User Code (ID do cliente 
registrado) e Verification URL (a URL onde o fluxo 
poderá prosseguir); 

4. O dispositivo apresenta o User Code e Verification 
URL para o cliente; 

5. Já no computador, o usuário utiliza um browser para acessar 
a URL de verificação, contendo seu código; 

6. O browser apresenta a tela de consentimento; 

7. Quando o usuário dá seu consentimento, o servidor de 
autorização marca o dispositivo como autorizado; 

8. Enquanto isso, o dispositivo móvel ficava fazendo polling no 
servidor para verificar se já havia uma resposta; 

9. Quando o dispositivo é marcado como autorizado, a 
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próxima requisição polling que o dispositivo fará vai obter o 
access token , permitindo que o fluxo continue pelo 
dispositivo móvel. 


Password Credentials Flow 


O fluxo de password credentials é um caso único dentre 
os fluxos de OAuth. Ele pressupõe confiança total no cliente, a 
ponto de o usuário fornecer o usuário e senha reais da aplicação 
terceira (ou seja, na realidade ele ignora aquela explicação do 
carro, valey key etc.). Estes casos são aqueles onde o cliente é o 
Sistema Operacional do computador, por exemplo. Mas também 
claramente é uma oferta para que os clientes iniciem migração de 
fluxos onde se utiliza HTTP Basic para autenticação utilizando 
OAuth. 


O fluxo funciona da seguinte forma: 


1. O usuário apresenta suas credenciais (usuário e senha) para 
o cliente, expressando seu desejo de utilizar os recursos do 
servidor de recursos; 

2. O cliente apresenta estas mesmas credenciais para o servidor 
de autorização; 

3. O servidor de autorização realiza a autenticação dos dados e 
devolve o access token; 

4. O cliente utilizao access token para acessar os dados. 


Existem também outros fluxos OAuth, bem como variações 
destes apresentados aqui. Em realidade, seria necessário um livro 
inteiro apenas para falar sobre OAuth (de fato, a Casa do Código 
tem um, chamado OAuth 2.0: Proteja suas aplicações com o Spring 
Security OAuth2, do Adolfo Eloy). Caso você se interesse pelo 
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assunto, é um ótimo ponto de partida para se aprofundar mais. 


9.4 AWS APIGATEWAY 


Eu não poderia escrever um livro sobre APIs sem falar de API 
Gateways. Esta é uma classe de sistemas cuja missão é 
principalmente monitorar APIs e retirar preocupações ortogonais 
destas, deixando detalhes de implementação apenas nos serviços. 
Isso inclui preocupações com autenticação/autorização, limitação 
de capacidade de uso, roteamento entre diferentes provedores do 
serviço etc. 


Existem vários API Gateways disponíveis no mercado. Um 
deles é o Kong (disponível em https://konghq.com/kong/), que é 
open source e pode ser instalado e gerenciado manualmente. No 
entanto, darei preferência aqui ao API Gateway da AWS, uma vez 
que a AWS é, no momento, um dos cloud providers mais utilizados 
no mundo. 


O console da AWS está disponível em 
https://aws.amazon.com/pt/console/. Você pode acessar o console 
e criar uma conta usando seu cartão de crédito. 


AVISO: enquanto existem muitas ferramentas AWS que você 
pode usar gratuitamente, algumas são pagas. No momento da 
escrita deste livro, o AWS API Gateway é gratuito para até 1 
milhão de chamadas da API por mês, conforme a seguir: 
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Nivel gratuito 


O nivel gratuito do Amazon API Gateway Inclui um milhão de chamadas de API recebidas para as APIs REST, um milhão de chamadas 
de API recebidas para as APIs HTTP e um milhão de mensagens e 750.000 minutos de conexão para as APIs do WebSocket por mês 
durante até 12 meses. Se o número de chamadas por mês for excedido, haverá cobrança de acordo com as taxas de uso do API Gateway. 





1 MILHÃO DE CHAMADAS DE API RECEBIDAS | 1 MILHÃO DE CHAMADAS DE API HTTP RECEBIDAS | 1 
MILHÃO DE MENSAGENS | 750.000 MINUTOS DE CONEXÃO 


por mês 


Essas ofertas de nível gratuito estão disponíveis somente para novos clientes da AWS pelo período de 12 meses a partir da data de 
cadastro na AWS. Quando o período de uso gratuito de 12 meses expirar ou se a utilização do aplicativo ultrapassar os níveis de uso 
gratuito, você simplesmente pagará as tarifas padrão de pagamento conforme o uso. 


Figura 9.8: Precificação do AWS API Gateway 


Uma vez logado, você verá uma página semelhante à seguinte: 


Console de gerenciamento da AWS 


serviços da AWS Acessar recursos em trânsito 
rem é cometa dm perorare por mene me 
Lecatizar erage nl tr de Como dr ts re E 
© Servas monsoon recomtemaras Explorar a AWS 
Amares Beane 


sanan comi ps md to us ES 


© serviços da AS 
Loreto comttimeses tem ter vtd tum a ABS Farpute 


O an rorya comenta o dm ver vemnbemaçes Ser o 


es e coeerestieeatens ence 


Esnas ema máquena rman Cotar om apination we Cotas namo vernon vireash — Regetrar nem finns Operações excalawrn Soren é tegres e barbus e 





+=] Lam RE = 
Figura 9.9: Página inicial do console da AWS 


Digite API Gateway na caixa central de busca e dê enter . 
Daí, você estará na página inicial do serviço API Gateway : 
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Serviços v Grupos de recursos v 


+ 


Amazon API Gateway 
criar, manter e proteger APIs em 


qualquer escala 


Escolher um tipo de API 


HTTP API 


Crie APIs REST de baixa latência e econômicas com 
recursos integrados, como OIDC e OAuth2, e suporte 
nativo a CORS. 


Funciona com o seguinte: 
Lambda, back-ends HTTP 





API WebSocket 


Crie uma API WebSocket usando conexões 
persistentes para casos de uso em tempo real, como 
aplicativos de bate-papo ou painéis. 


Funciona com o seguinte: 
Lambda, HTTP, produto da AWS 


Compilar 





API REST 
Desenvolva uma API REST na qual você obtenha 


controle total sobre a solicitação e a resposta Junto 
com os recursos de gerenciamento da API. 


Funciona com o seguinte: 


API REST privada 


Crie uma API REST que seja acessível somente de 
dentro de uma VPC. 


Funciona com o seguinte: 
Lambda, HTTP, produto da AWS 


Figura 9.10: Página principal do AWS API Gateway 


Quando clicamos no botão Compilar 


da caixa HTTP API, 


somos levados a uma tela onde há uma mensagem de boas-vindas: 
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Criar sua primeira API 


Bem-vindo ao Amazon API Gateway! Para criar sua primeira API, preenchemos o 
formulário de importação com a API Petstore definida usando o Swagger 2.0. Para 
começar. feche esta janela restrita e selecione Importar no formulário de criação de AP! 


OK 








Figura 9.11: Mensagem de boas-vindas do AWS API Gateway 


Ao clicar no botão OK, você poderá conferir o passo a passo 
da criação da API, conforme oferecido pela AWS. No momento, 
existem duas opções disponíveis: via AWS Lambda e via HTTP. 
Nosso interesse é via HT'TP. 


Criar uma API 


Criar e configurar integrações 


Especifique on serviços de back-end com os qaan was APY se comurucará Esses são chamados de integrações Para uma integração do Lambda. O API Gateway invoca a função do Lambda e responde 
com a resposta da função. Para integração MTTP. o API Gateway ervia a solicRacSo para o URL expeciicado e retorna a resposta do URL 


Tipo de integração Destino da Integração 


Adicionar integração 


Nome da APY 


Figura 9.12: Criar API HTTP no AWS API Gateway 


Entretanto, temos um problema fundamental: nosso serviço, 
pelo menos no momento, está disponível apenas na nossa máquina 
local. É muito complicado realizar a exposição desse serviço em 
nossa máquina local sem configurações de NAT no roteador (algo 
que pode ser inviável se você estiver disponibilizando-o na sua 
empresa). Existe uma ferramenta que pode nos ajudar com essa 


304 9.4 AWS API GATEWAY 


tarefa, chamada ngrok . O ngrok atua exatamente como seu 
roteador, mas criando um DNS específico para sua máquina. Este 
endereço estará disponível na internet e ao alcance de todos - o que 
permite que uma requisição da AWS chegue diretamente à sua 
máquina. 


Vamos acessar a página do ngrok em https://ngrok.com/. Ao 
clicar no botão de download, nos deparamos com uma tela 
semelhante à seguinte: 


Th ngrok -download x 

e Œ ü ngrokcom/downlood t OOvr m- ove Je: 

Ht Apps qrcodeservice Wa interessantes @ Favoritos @ Java (i) whatiLearne. ” 
ng rok HOW IT WORKS PRICING DOWNLOAD DOCS ENTERPRISE SOLUTIONS 


Download & setup ngrok 


Get started with ngrok in just a Few seconds. 


(1) Download ngrok © Unzip to install 
First, download the ngrok client, a single binary On Linux or OSX you can unzip ngrok from a 
with zero run-time dependencies. terminal with the following command. On 


Windows, just double click ngrok.zia. 


ee [rt pa 


Most people like to keep ngrok in their primary 
user folder or set an alias for easy command-line 
access. 





@ Connect your account (©) Fire it up 


Running this command will add your authtoken to Try it out by running it from the command line: 
your ngrok.ymi file, Connecting an account will list 


sadio aaah colapso! aed oy [mara O] 
longer tunnel timeouts, and more. Visit the 


dashboard to get your auth token. 









To start a HTTP tunnel on 
Es coa Ask a question 





Figura 9.13: Download do Ngrok 


Nesta tela, existem as instruções de como baixar e utilizar o 
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ngrok , de acordo com seu sistema operacional. Observe que, no 
meu caso, é um sistema operacional Linux e, portanto, basta 
baixar, descompactar o zip e utilizar. Não é obrigatório cadastrar o 
token conforme informado na página, mas algumas features só 
estão disponíveis se você o fizer. 


Para disponibilizar nossa API com HTTPS via ngrok , o 
comando é ngrok http https://localhost:8080 . Isso vai 


provocar um alerta como o seguinte: 





Figura 9.14: Tentativa de execução do Ngrok com HTTPS 


Esbarramos em um novo problema. O ngrok com HTTPS só 
estará disponível se você fizer o registro no site. Se for o caso, basta 
se autenticar no site do ngrok e cadastrar o token conforme 
instruído no site. Mas caso você não queira fazer esse 
procedimento, podemos remover a camada de segurança da nossa 
API, abrindo o arquivo application.properties e colocando 

# na frente das linhas que definem o SSL da nossa aplicação: 
app.car.domain.googlemaps.apikey=SUA API KEY 
gserver.ssl.key-store=classpath:keystore.p12 
#server.ssl.key-store-password=restbook 
#server.ssl.key-store-type=PKCS12 


#server.ssl.key-alias=car 


Vamos então inicializar nossa API novamente e inicializar o 
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ngrok com o comando ngrok http 8080 . Uma tela semelhante 
à seguinte deve ser vista: 


asaudate@ni-17935-0: ~/Software/ngrok-stable-linux-amd64 


asaudate@ni-17935-0: ~ ware/ngrok-stable-linux-amd64 80x24 





Figura 9.15: Ngrok servindo HTTP na porta 8080 


Observe que um endereço do tipo 
http://xxxxxxxx.ngrok.io foi criado. Este endereço muda a 
cada execução, então temos que tomar o cuidado de realizar os 
passos seguintes todos de uma vez só. 


O próximo passo é voltar ao painel de controle da AWS e 
adicionar nossa primeira integração. Ao clicar no botão 
Adicionar integração , selecione o campo HTTP e, como 
destino da integração, deixe ANY (isso significa que todas as 
requisições para o mesmo endereço, independente do método 
HTTP serão roteadas para o mesmo endereço de destino). Vamos 
então configurar o endereço conforme a seguir para apontar para 


criar a API de motoristas: 
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Criar e configurar integrações 


Expecinque os serviços de back-end com os quais sus API se comunicará Esses são chamados de untegrações Para uma integração do Lambda, o AP Gateway invoca a função do Lambda e responde 
com a resposta da função. Para intogração HTTP, o API Gateway envia a solicitação para o URL especificado e retorna a resposta do URL 


Tipo de integração Destino da integração 


wre © w % —_tttpc//92923451 ngrokiojdrvers x 


Adicionar integração 


Nome da APY 


<r 


Figura 9.16: Adicionando a primeira integração no API Gateway 





Quando esse passo é realizado, clique no botão Avançar 
Uma tela de resumo das configurações será apresentada: 





Configurar rotas 
O API Gateway Usa rotas para expor Integrações aos conuamadores da tua AP As rotas para APIS HTTP consistem em daas partes um metodo HTTP e um camunho de rec 
/pets). Você pode definir métodos HTTP especificos para us integração (GET, POST, PUT, PATCH, HEAD, OPTIONS e DELETE) ou usa o metodo ANY para combinar todos 
denn em um determenado recurso 
Método Caminho do recurso Destino da integração 
any ’ ionen ANY http //5232545 9 ngrok so/drwvers . x 


Adicionar rota 


Figura 9.17: Revisando a primeira integração no API Gateway 


Quando clicamos em Avançar , uma nova tela é apresentada, 
onde a configuração dos estágios da API é realizada. Os estágios 
são semelhantes aos ambientes de desenvolvimento em uma 
empresa, ou seja, algo como desenvolvimento , homologação , 

sandbox , produção etc. Perceba que, ao entrar na tela, a AWS 
sugere o nome $default como padrão. Vamos alterar para dev 
(diminutivo de desenvolvimento) e deixar marcada a caixa de 
implantação automática. Isso significa dizer que todas as alterações 
feitas naquilo que está publicado neste estágio estará 
disponibilizado imediatamente para o público, o que é feito para 
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realizar um controle de aprovação (caso o estágio seja de produção, 
por exemplo). Em ambiente de desenvolvimento, não precisamos 
de tanta cautela e, portanto, a caixa pode permanecer marcada: 


Configurar estágios 


Estágios são ambieetes configurdvets de forma independente mo quais sus API pode ses implantada Uma API deve ser wnplactada em um estágio antes que qualquer alteração na sua configuração 
se tome disponível, a não ser que esse estágio esteja configurado para implantação automática. Por padrão, todas as APIs HTTP criadas por meio do console tèm um estágio padrão chamado 
Sdetauit, e todas as alterações feitas na ssa APY serdo implantadas automaticamente nesse estágio Você pode adicionar mais estigos que representam ambientes como desenvolvimento ou 
procução 


Nome do estágio Implantação automática 





Figura 9.18: Definição de estágios no API Gateway 


Finalmente, ao prosseguir com a criação, a AWS nos apresenta 
uma última tela para realizar a revisão de tudo que foi criado até 
aqui: 


Analisar e criar 


Nome e integrações da API Editar 


Nome da API 
Drivers 
Integrações 


ANY http://52323451.ngrok.to/drivers (HTTP) 








Rotas Editor 


Rotas 
ANY /drivers — ANY http://5232345 1 .ngrok io/drivers (HTTP) 


Stages | Editar 





Estaglos 
dev (Auto-deploy: enabled) 


i 
comentar [ vetar | E 


Figura 9.19: Revisão final da configuração do API Gateway 
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Quando clicamos no botão Criar , o API Gateway nos 
apresenta o painel de controle da API que criamos e, agora, esta 
disponível para realizar a invocação. Observe o campo Invocar 
URL : 


€ > CG @ console.aws.amazon.com/apigateway/main/api-detail?api= t OOryFHSL O€¢ o i 





Hi Apps ~) qrcode-service W Pullrequestsf... €@ Kanban Mosc... {@ Moscou [PAG... Bm Interessantes » 








Serviços v Grupos de recursos v 








Drivers (ceth876abb) criada com éxit 





API Gateway Detalhes | implantar | 
Drivers 


Detalhes da API 

ID da API Protocolo Criado(a) 
ceth876abb HTTP 2020-04-05 
Descrição 


No Description 





Estágios para a Drivers 


Q 
Nome do Implantação Implantação Última 
hig Invocar URL x ‘ae er 
estagio anexada automática atualização 


https://ceth876abb.execute 
dev -apl.us-east- 4tcz3x enabled 2020-04-05 
1.amazonaws.com/dev 





@ comentários @ Portugués Política de p 








Figura 9.20: API Gateway mostrando o painel de controle da nova API 


Segundo este campo, a API está publicada no endereço 
https://ceth876abb.execute-api-us-east-1.amazonaws.com/dev (no 
caso deste exemplo específico). Assim sendo, podemos realizar a 
request para esse endereço, acrescido de /drivers . Todo o 
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restante permanece exatamente da mesma forma como era antes, 


como o corpo da requisição e os cabeçalhos. A requisição ficará 
assim: 


Postman 


File Edit Vie 


ê, Invite G a ae we J 





local 
OPT Lista GET Re post Cr Pas i wow? https:/.@ + ou. 


Untitled Request 











POST Y https://ceth876abb.execute-api.us-east-1.amazonaws.com/dev/drivers 
Params Authorization @ Headers (10) Body © Tests Settings 
Query Params 
KEY VALUE DESCRIPTION 
Body Cookies Headers (14) Test Results 2000K Time: 2.85s ze; 479 B 
Pretty Raw Preview Visualize JSON >» = 
1 ff 
2 "id": 2, 
3 "name": "string", 
4 "birthDate": null 
5 Ẹ 
E fal t+” Bootcamp a B 


Figura 9.21: Request via Postman ao API Gateway 
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SE CRIAMOS A API MAPEADA PARA /DRIVERS , POR QUE PRECISAMOS 
INCLUIR NOVAMENTE NA REQUISIÇÃO? 


Quando criamos o mapeamento na AWS, inserimos o 
endereço do ngrok eo path /drivers . Isso porque cada 
um dos paths no API Gateway pode ser mapeado de maneira 
independente. Se alguma requisição chegar para um path que 


não está mapeado, ela não é entregue. Assim sendo, em 


realidade não estamos configurando /drivers como uma 
espécie de atalho; estamos apenas informando o API Gateway 
para liberar requisições para esse path. Quando realizamos a 
requisição pelo Postman estamos, portanto, tomando 
proveito desse mapeamento. 





Ao utilizar um API Gateway como o da AWS, podemos retirar 
da aplicação várias preocupações com o uso da API e deixar 
somente algumas. Preocupações como autenticação/autorização, 
HTTPS, CORS e outras podem ser configuradas diretamente no 
API Gateway, tirando a necessidade de se configurar diretamente 
na aplicação. 


No menu da esquerda do painel, você pode conhecer algumas 
dessas opções. Um exemplo é o controle de tráfego que será feito. 
Esta configuração permite que se bloqueie o excesso de tráfego 
externo à aplicação, poupando a API de uma eventual queda por 
excesso de requisições. 


Para acessar essa configuração, clique no menu à esquerda 
sobre a opção Controle de utilização . Uma vez selecionado o 
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estágio onde a configuração sera realizada (no nosso caso, só temos 
dev no momento), um menu como o seguinte será apresentado: 


Controle de utilização para o estágio dev 


Configurações de rota no estágio Controle de utilização de rotas selecionadas 


ai 





Controle de utilização padrão de rotas Cites 


Nebo configurado tão configurado 


Controte de utilização da conta 


Figura 9.22: Configurações de throttling 


No momento, o API Gateway estará configurado com as 
configurações padrão: até 5000 requisições simultâneas (no mesmo 
milissegundo) e até 10000 requisições no mesmo segundo. 


Conclusão 


Neste capítulo, conhecemos várias outras técnicas que vão nos 
ajudar a construir uma API excelente e que vai impulsionar nosso 
sistema para ser mais e mais embutido em outras aplicações, 
alavancando o sucesso da nossa própria aplicação. 


Nós vimos como criar um bom mecanismo de paginação, 
garantindo que o retorno das requisições será leve e fácil de ser 
utilizado pelos clientes. 


Vimos também para que serve e porque configurar CORS - 
algo muito importante se quisermos que nossa API apresente 
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interoperabilidade com clientes escritos em JavaScript. 


Vimos como criar autenticação e autorização utilizando 
OAuth, um poderoso recurso para quando queremos oferecer 
nossa aplicação para ser interoperável não apenas com clientes 
diretamente, mas também com outras aplicações. 


E finalmente, aprendemos a utilizar um recurso poderosíssimo 
para a efetiva exposição da nossa API para o mundo, o API 
Gateway. Vimos como funciona, então o API Gateway de um dos 
principais players do mercado, a Amazon Web Services - AWS. 


No próximo capítulo, vamos começar a fazer uma revisão geral 
de tudo que vimos ao longo deste livro, para ter certeza de que não 
deixamos nenhuma informação importante esquecida. Vamos em 
frente? 
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CapituLo 10 


CONSIDERACOES FINAIS 


"O professor não ensina, mas arranja modos de a própria 
criança descobrir. Cria situações-problemas.” - Jean Piaget 


Existem várias técnicas em APIs REST que eu gostaria de ter 
abordado neste livro. No entanto, o espaço de que disponho é 
limitado, então fazer isso não seria possível. 


Assim sendo, a seguir enumero vários destes assuntos e como 
eles podem contribuir para os seus conhecimentos neste universo 
de APIs. 


Cloud computing 


Certamente um dos assuntos que estão mais em alta 
ultimamente. É muito importante que desenvolvedores de APIs 
detenham o máximo de conhecimento sobre cloud computing, já 
que muitos provedores oferecem ferramentas especializadas para 
uso neste tipo de desenvolvimento. 


Neste livro, eu abordei o AWS API Gateway. Observe que a 
AWS oferece várias ferramentas que estão interligadas com esse 
universo, como o Route 53 (para administrar DNS) e Cloudfront 
(para criação de content delivery networks, ou CDNs ), além de 
diversas opções de implantação das APIs em servidores 
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gerenciados. Da mesma forma, os concorrentes da AWS (como 
Google Cloud Platform e Microsoft Azure) oferecem muitas 
ferramentas nesse sentido. 


Serverless 


Ao abordar API Gateways, confesso a vocé que fiquei tentado a 
me debruçar neste mesmo livro sobre o tema serverless. Trata-se de 
uma forma de criar e executar uma aplicação em nuvem sem ter 
que lidar com o fardo de criar e gerenciar vários aspectos de 
servidores gerenciados - a própria nuvem faz isso por nós. Quando 
utilizamos serverless (do inglês sem servidor) nós precisamos nos 
preocupar apenas com o código em si e na forma como ele está 
exposto para o mundo, mas não com detalhes da execução do 
código. Isso faz desta uma técnica extremamente poderosa e 
barata (já que o provedor de nuvem aloca processamento para o 
código apenas quando é estritamente necessário, derrubando os 
custos de manter um servidor executado o tempo inteiro). 


Não bastassem estes aspectos, APIs serverless hoje são as mais 
escaláveis conhecidas, já que, como o processamento é gerenciado 
diretamente pelo cloud provider que estamos utilizando, a 
escalabilidade destas tende a ser o tanto quanto o provedor puder 
disponibilizar. A AWS, hoje, é responsável por grande parte do 
tráfego mundial de internet. 


CQRS 


O padrão CQRS, Command Query Responsibility Segregation, é 
uma alternativa às APIs REST. Em outras palavras, uma API 
CQRS não pode ser considerada RESTful, pois não tem as mesmas 
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características de um serviço REST. Estas são feitas de maneira a 
lidar com questões que são mais complexas de se lidar em APIs 
RESTful, como buscas com parâmetros complexos e cenários onde 
a criação de recursos e a efetiva localização destes é destoante. O 
CQRS tem a missão de separar os aspectos de criação/atualização 
de recursos dos aspectos de localização destes. 


GraphQL 


Uma técnica que também não é RESTful, mas tem a missão de 
criar uma API onde seja possível criar buscas de forma dinâmica, 
sem ser necessário deixá-las previamente criadas no lado do 
servidor. Ao utilizar GraphQL, o cliente pode submeter a sua query 
customizada e pesquisar informações de acordo com sua 
necessidade - semelhante ao que ocorre conosco quando 
utilizamos um banco de dados relacional, por exemplo. Para saber 
mais sobre GraphQL, visite o site https://graphql.org/. Você 
também pode conhecer o livro 
https://www.casadocodigo.com.br/products/livro-graphql. 


OAuth 


No capítulo 9, eu abordei OAuth de maneira superficial, 
apenas por considerar o quanto é importante o conhecimento 
sobre esta técnica. Felizmente, existe um livro na Casa do Código 
inteiramente dedicado ao assunto, disponível em 
https://www.casadocodigo.com.br/products/livro-oauth. É um 
ótimo ponto para que você possa se aprofundar mais sobre o 
assunto. 
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JWT 


Ainda no quesito “segurança de APIs", temos o JWT - JSON 
Web Token. Trata-se de um padrão criado para que o próprio 
sistema de segurança da API consiga trafegar mais dados sobre o 
usuário do que tão somente o nome do usuário e senha. Isso 
habilita cenários complexos de autenticação e autorização 
envolvendo múltiplos participantes, tornando o conhecimento em 
JWT algo crucial para o desenvolvimento de APIs públicas e 
interconectadas. Para saber mais, visite o site https://jwt.io/. 


Reactive APIs 


As APIs reativas oferecem uma forma moderna de se lidar com 
concorrência em ambientes que são requisitados por muitos 
usuários ao mesmo tempo. Elas fazem um uso melhor de I/O não 
blocante, o que por sua vez as leva a utilizarem de maneira mais 
eficiente recursos externos. Assim sendo, são extremamente úteis 
em contextos de múltiplos microsserviços. 


gRPC 


gRPC é uma forma de criar APIs RPC (Remote Procedure Call - 
Chamada remota de procedimento). Em oposição a REST, onde a 
ação é executada no servidor de forma indireta, em RPC o cliente 
determina exatamente qual é a ação a ser invocada. Por exemplo, 
uma chamada RPC hipotética poderia ter o seguinte formato: 


POST /actions 


"acao":"criarPassageiro", 
"dados": "n W 


} 
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O gRPC é uma abordagem para APIs RPC que nasceu no 
Google e hoje é incubado em um projeto chamado Cloud Native 
Computing Foundation. O gRPC visa tornar comunicações RPC 
mais eficientes através do uso de uma ferramenta de serialização 
nascida no Google chamada Protocol Buffers. Através desta 
ferramenta, os formatos de dados são pré-compilados, o que 
viabiliza a serialização mais rápida de dados. 


Em linhas gerais, o gRPC se opõe a REST em quase todos os 
aspectos. Uma arquitetura de APIs eficiente poderia se beneficiar 
de ambos os formatos - oferecer mais opções de uso para os 
clientes pode ser bastante benéfico para todos. 


Para saber mais sobre o gRPC, visite o site https://grpc.io/. 
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